API conventions and errors
Response envelopes, authentication boundaries, errors, CORS, and version stability.
Response envelope
Successful and unsuccessful JSON responses share one top-level shape:
type ApiResponse<T> = {
code: number;
message: string;
data: T | null;
};code: 0 means the operation succeeded. Always check the HTTP status first,
then use code for application-level handling.
Common application codes
| Code | Meaning |
|---|---|
0 | Success |
1000 | Invalid request or authentication service unavailable |
1001 | Missing, expired, or invalid authentication |
1003 | Invalid SIWE request or signed message |
1004 | Requested user-owned record was not found |
1009 | Username already exists |
2000 | Market dependency error |
2100 | eToro integration, response, or rate-limit error |
3001 | The API is not ready because a required dependency is down |
4020 | An x402 payment is required |
4021 | The x402 payment service is not configured |
Authentication boundary
User profiles and watchlists require either a StonkTrader bearer credential or a signed SIWE session. Public health, metadata, authentication discovery, stock token listings, and market quote routes do not require platform login.
Trading requests use wallet addresses, signatures, and route-specific validation. Read each trading operation's schema before submitting a request.
Browser origins
StonkTrader browser applications and registered partner origins can call the
public API directly. Unregistered browser origins do not receive an
Access-Control-Allow-Origin response. Server-to-server HTTPS calls are not
subject to browser CORS enforcement.
Version stability
2.0.0 is frozen for this release. Changes within the same release line
will be additive or corrective. An incompatible path, authentication, request,
or response change requires a new documented API version.
Use /meta/version to identify the deployed API version and exact source
commit. Use /meta/capabilities to discover the currently supported native
service inventory.