RFQs and quotes¶

POST /rfqs¶

Use this to create a quote request.

Header:

• Idempotency-Key (required)

Semantics:

• RFQ expires at created_at_ms + ttl_ms
• Quote expiry must be within RFQ TTL

Core request fields:

• account_id (required when mode=firm)
• from_asset_key|from_symbol (one required)
• to_asset_key|to_symbol (one required)
• side: exact_in or exact_out
• amount:
• exact-in: amount_in_atoms or amount_in_ui
• exact-out: amount_out_atoms or amount_out_ui
• mode: indicative or firm

When using *_ui fields, enforce decimal precision from the asset's decimals value. Too many fractional digits will return 400 ui_precision_exceeded.

Destinations must be pre-registered via the address book. Trade requests reference a destination_id — inline addresses are not accepted.

Exception: recovery claims use inline destination details on POST /public/recover-funds.

Parameters¶

Indicative vs firm TTL¶

For indicative quotes displayed in a UI, use a longer ttl_ms (e.g. 5000–10000) to reduce request volume. The default 1000 is tuned for firm execution. Indicative quotes are not executable — a separate firm RFQ is required to trade.

Example request:

curl -X POST https://routes.srcry.xyz/v1/rfqs \
  -H "Authorization: Bearer $ROUTES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
  "account_id": "acct_01J...",
  "credit_id": "cred_01J...",
  "from_asset_key": "spl.solana:XYZMINT...",
  "to_asset_key": "native.zec",
  "side": "exact_in",
  "amount_in_ui": "1000",
  "mode": "firm",
  "ttl_ms": 1000,
  "wait_ms": 250,
  "destination_id": "dest_01J..."
}'

import httpx

response = httpx.post(
    "https://routes.srcry.xyz/v1/rfqs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": "unique-key-123",
    },
    json={
        "account_id": "acct_01J...",
        "credit_id": "cred_01J...",
        "from_asset_key": "spl.solana:XYZMINT...",
        "to_asset_key": "native.zec",
        "side": "exact_in",
        "amount_in_ui": "1000",
        "mode": "firm",
        "ttl_ms": 1000,
        "wait_ms": 250,
        "destination_id": "dest_01J..."
    },
)

const response = await fetch("https://routes.srcry.xyz/v1/rfqs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "unique-key-123",
  },
  body: JSON.stringify({
    account_id: "acct_01J...",
    credit_id: "cred_01J...",
    from_asset_key: "spl.solana:XYZMINT...",
    to_asset_key: "native.zec",
    side: "exact_in",
    amount_in_ui: "1000",
    mode: "firm",
    ttl_ms: 1000,
    wait_ms: 250,
    destination_id: "dest_01J..."
  }),
});

{
  "account_id": "acct_01J...",
  "credit_id": "cred_01J...",
  "from_asset_key": "spl.solana:XYZMINT...",
  "to_asset_key": "native.zec",
  "side": "exact_in",
  "amount_in_ui": "1000",
  "mode": "firm",
  "ttl_ms": 1000,
  "wait_ms": 250,
  "destination_id": "dest_01J..."
}

Response behavior:

• 200 ready includes best_quote_id when ready within wait_ms
• otherwise 202 pending includes rfq_id and poll_after_ms

200 example:

{
  "request_id": "req_01J...",
  "rfq": {
    "rfq_id": "rfq_01J...",
    "status": "ready",
    "best_quote_id": "qt_01J..."
  }
}

Response fields (200)¶

202 example:

{
  "request_id": "req_01J...",
  "rfq": {
    "rfq_id": "rfq_01J...",
    "status": "pending",
    "poll_after_ms": 250
  }
}

Response fields (202)¶

Idempotency semantics:

• same key + same payload -> same rfq_id and stable logical response
• same key + different payload -> 409 idempotency_key_reuse
• replay while in-flight -> 202 with same rfq_id

GET /rfqs/{rfq_id}¶

Use this to poll an RFQ until ready.

Example response:

{
  "request_id": "req_01J...",
  "rfq": {
    "rfq_id": "rfq_01J...",
    "status": "ready",
    "best_quote_id": "qt_01J..."
  }
}

GET /quotes/{quote_id}¶

Use this to retrieve a selected quote and route metadata. This endpoint does not expose solver execution plans.

Documented route metadata:

• route_type: INTENTS_ONLY, HYBRID_SOLANA_TO_INTENTS, LOCAL_CHAIN_SWAP
• settlement_domains
• fees — platform and integrator fee breakdown (see Fees)
• route_requirements (for example min_intermediate_out)

Example response:

{
  "request_id": "req_01J...",
  "quote": {
    "quote_id": "qt_01J...",
    "rfq_id": "rfq_01J...",
    "mode": "firm",
    "expires_at_ms": 1730000010000,
    "route_type": "HYBRID_SOLANA_TO_INTENTS",
    "settlement_domains": [
      "solana",
      "destination_settlement"
    ],
    "from_asset_key": "spl.solana:XYZMINT...",
    "to_asset_key": "native.zec",
    "side": "exact_in",
    "amount_in_atoms": "1000000000",
    "expected_out_atoms": "100000000",
    "fees": {
      "platform_bps": "5",
      "integrator_bps": "10",
      "total_bps": "15",
      "platform_atoms": "50000",
      "integrator_atoms": "100000",
      "total_atoms": "150000"
    },
    "route_requirements": {
      "min_intermediate_out": {
        "asset_key": "spl.solana:USDCMINT...",
        "min_out_atoms": "123450000"
      }
    }
  }
}

Response fields¶