API reference¶

This page documents the stable HTTP contract for Routes API v1. For a walkthrough, see Getting started.

For failed-zap recovery activation and public claim flow, see Recoveries.

Routes is a REST API for pricing and executing crypto swaps across many chains and assets using a single, consistent identifier model. Integrators call Routes on behalf of their end users. End users are not required to sign blockchain transactions as part of the API flow.

Authorization and scoping¶

Your API key authenticates your organization and grants access to all accounts within it. Multiple team members may hold API keys for the same organization — they share access to all resources.

API keys are issued out-of-band per organization. For provisioning, rotation, or revocation, contact Routes support. For safe rotation, cut over to a new key before revoking the old key.

Endpoints fall into four scoping tiers:

Account-scoped — require account_id in the path (/accounts/{account_id}/...). These operate on a specific end user's credits, destinations, deposits, balances, and activity.

ID-based — take a resource ID in the path (/trades/{trade_id}, /zaps/{zap_id}, /rfqs/{rfq_id}, /quotes/{quote_id}, /cancels/{cancel_id}, /recoveries/{recovery_id}). Resource IDs are globally unique — account_id is not required at lookup time. Your API key can access any resource belonging to any account in your organization.

Global — operate across all accounts: webhooks, symbols, assets, instruments, markets, and the event feed (GET /v1/events).

Public (no bearer auth; OTP where applicable) — these endpoints do not use bearer auth. Some use email OTP:

• POST /v1/public/recover-funds — claim a failed-zap recovery credit (OTP required). See Recoveries.
• POST /v1/public/initiate-export — begin user-initiated key export and send OTP. See Accounts.
• POST /v1/public/complete-export — verify OTP and lock account for export. See Accounts.
• GET /v1/public/export-status — poll export progress and retrieve encrypted keys (OTP session proof required). See Accounts.

Contract header¶

• Base URL: https://routes.srcry.xyz/v1
• Environment availability: production only; no sandbox/test environment currently available
• Auth header: Authorization: Bearer <api_key>
• Content type: application/json
• Responses are JSON unless explicitly documented otherwise (for example 204 No Content)
• Amount encoding: all amount fields are strings (*_atoms, *_ui)
• Trades execute asynchronously; status is available via polling and webhooks

Idempotency required on:

• POST /accounts
• POST /accounts/{account_id}/export-keys
• POST /accounts/{account_id}/deposit-addresses
• POST /rfqs
• POST /quotes/{quote_id}/accept
• POST /zaps
• POST /cancels
• POST /recoveries/{recovery_id}/activate

Idempotency conflict: 409 idempotency_key_reuse

Idempotency keys¶

Idempotency keys can be any string. Recommended format: UUID v4 (e.g. 550e8400-e29b-41d4-a716-446655440000). Reuse the same key when retrying the same write request with the same payload.

Idempotency keys are retained for at least 24 hours and may be pruned after that window.

Defaults¶

Request parameter defaults (override per-call):

• ttl_ms: 1000
• wait_ms: 250
• limit: 50 (max 100)

Trade size¶

Trades and zaps should have notional value between $1 and $100,000 USD equivalent. Requests outside this range may fail with insufficient_liquidity or validation errors.

Core objects¶

Accounts¶

account_id identifies an end-user account provisioned via POST /accounts. Balances, activity, and trading permissions are scoped to an account.

Assets¶

Routes executes swaps between assets. An asset is a specific, spendable instance of value on a particular chain or venue (for example an ERC-20 contract on an EVM chain, an SPL mint on Solana, or a native L1 coin).

Execution is always:

from_asset -> to_asset

Identifier fields:

• asset_key: canonical deterministic identity (stable, never reused)
• symbol: organization-scoped alias registered via PUT /symbols

Supported assets are discovered programmatically via GET /assets. Documentation examples are illustrative and not an exhaustive support list.

See Identifiers for the full asset_key grammar, canonical forms, and partner symbols.

RFQs, quotes, and trades¶

Routes separates pricing from execution:

• rfq_id: pricing job (fan-out to solvers/MMs and aggregation)
• quote_id: returned offer (indicative or firm)
• trade_id: created when a firm quote is accepted and execution begins
• zap_id: created for market-order execution (no quote/accept cycle)

All trading is sourced from credits. A credit (credit_id) is a spendable balance created when a deposit is verified (chain finality reached and source address passes screening), when a trade settles, or as change from a partially-used credit. Firm RFQs require a credit_id specifying which credit to draw from. Zaps accept an optional credit_id: if provided, execution starts immediately; if omitted, the zap returns a deposit address and enters awaiting_deposit until funds are verified. Each trade fully consumes its source credit — if the trade uses less than the full amount, a new change credit is created for the remainder.

Fees¶

Every trade includes two fee components:

• Platform fee — charged by Routes, configured per organization. Expressed in basis points of the output amount.
• Integrator fee — optional markup set by the integrator. Passed per-request via integrator_fee_bps (supports decimal values, e.g. "2.5") or configured as a default on your organization.

Both fees are deducted from the output amount. The quote response includes a fees object showing the breakdown. The expected_out_atoms field is net of all fees — it is the amount the end user receives.

If integrator_fee_bps is passed on a request, it overrides the organization default for that request.

Response envelope and request IDs¶

Every response includes request_id (success and error).

Singular resources are wrapped:

• { "account": { ... } }
• { "asset": { ... } }
• { "rfq": { ... } }
• { "quote": { ... } }
• { "trade": { ... } }
• { "zap": { ... } }
• { "cancel": { ... } }
• { "recovery": { ... } }
• { "destination": { ... } }
• { "deposit_address": { ... } }
• { "webhook": { ... } }

Collection/list responses return typed arrays with pagination metadata where applicable.

Error codes¶

All errors use a common envelope:

{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing",
    "message": "Missing required param: amount_in_atoms",
    "param": "amount_in_atoms",
    "request_id": "req_01J..."
  }
}

HTTP status usage¶

• 400 invalid parameters / validation errors
• 401 missing or invalid auth
• 403 forbidden by policy
• 404 not found / not available
• 409 conflict (idempotency_key_reuse, quote consumed)
• 422 semantic validation failure for otherwise well-formed requests (for example email_not_configured)
• 429 rate limited
• 5xx server or upstream failures

Validation¶

Policy and availability¶

RFQ / quote / trade / zap / cancel lifecycle¶

Idempotency¶

• idempotency_key_reuse

For POST /v1/rfqs:

• missing Idempotency-Key -> 400, code=parameter_missing, param=Idempotency-Key
• reused key with different payload -> 409, code=idempotency_key_reuse

Rate limiting¶

• rate_limited

On throttling, the API responds with HTTP 429. Retry strategy:

1. Respect Retry-After when present.
2. Use jittered exponential backoff.
3. Reuse the same Idempotency-Key when retrying writes.
4. Resume list/event reads from the last stable cursor or watermark.
5. Treat idempotency_key_reuse as hard conflict (409).

Error recovery playbook¶

Use this table for first-response handling during integration and on-call.

Recoverability values:

• auto_retry — retry later without changing business intent
• manual_retry — caller must change input or flow before retry
• non_recoverable — do not retry blindly; escalate or start a new flow

Rate limits¶

Limits are applied per API key. Exceeding a limit returns 429 with a Retry-After header. For indicative pricing in a UI, use a longer ttl_ms (see RFQs — Indicative vs firm TTL) to reduce request volume rather than polling at high frequency.