# Conventions, envelope and errors

Every response uses the same envelope:

```json
{ "success": true,  "data": { ... } }
{ "success": false, "error": { "code": "NO_ROUTE", "message": "...", "retryable": false } }
```

## Hard rules

- **Amounts are decimal strings in BASE units** (wei, lamports, raw token units) — never numbers, never human-readable decimals. `"1000000000"` is 1 SOL.
- **Addresses**: checksummed `0x…` on EVM, base58 mints on Solana. Native asset uses the sentinel `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (EVM) or the wrapped-SOL mint (Solana).
- **Chains** are the literal strings `solana`, `ethereum`, `base`, `arbitrum`, `bsc`, `polygon`.
- **Pagination** uses opaque cursors: send `?limit=` and `?cursor=`, read `nextCursor` (null means end).
- **Quotes expire.** Re-quote instead of reusing a stale one; build endpoints re-quote internally.

## Error codes

`error.code` is a closed set — handle these exactly:

| code | HTTP | meaning |
| --- | --- | --- |
| `VALIDATION_ERROR` | 400 | malformed request body or params |
| `UNSUPPORTED_CHAIN` | 400 | chain not supported for this operation |
| `UNSUPPORTED_VENUE` | 400 | venue lacks this capability, or the asset is permissioned |
| `TOKEN_NOT_FOUND` | 404 | unknown token or asset id |
| `MARKET_NOT_FOUND` | 404 | unknown market id for that venue |
| `NO_ROUTE` | 404 | no provider could route this pair |
| `INSUFFICIENT_LIQUIDITY` | 422 | route exists but cannot fill the size |
| `PROVIDER_ERROR` | 502 | an upstream venue or chain RPC failed — retryable; on build endpoints you may also pass simulate:false |
| `PROVIDER_RATE_LIMITED` | 503 | upstream or our free tier throttled you — back off |
| `QUOTE_EXPIRED` | 410 | the quote or action went stale; re-request it |
| `SIMULATION_FAILED` | 422 | the built tx reverts in simulation; revert reason in details |
| `NOT_FOUND` | 404 | no such route |
| `INTERNAL` | 500 | our bug — safe to retry once |

Provider outages always degrade to `PROVIDER_ERROR` / `PROVIDER_RATE_LIMITED` envelopes — never a 500, never a partial-looking success.