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 |
3001 | The API is not ready because a required dependency is down |
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-alpha.2 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.