Skip to content

Partner symbols

Partners can register custom symbols that map to Routes canonical asset keys. Symbols are scoped to your organization and accepted anywhere an asset_key is accepted in requests. Responses always use canonical asset_key — symbols are not echoed back.

Constraints:

  • 2–32 characters, [A-Za-z0-9._:-], must start and end with [A-Za-z0-9]
  • Case-insensitive for lookup, case-preserving for storage
  • Bijective: each symbol maps to exactly one asset key, each asset key maps to at most one symbol within your organization

PUT /symbols

Bulk upsert symbol mappings. Idempotent. Atomic — if any mapping fails validation, the entire batch is rejected.

Parameters

Parameter Type Required Description
symbols array Yes Array of symbol mappings
symbols[].symbol string Yes Partner-defined symbol (2-32 chars, [A-Za-z0-9._:-], must start/end with alphanumeric)
symbols[].asset_key string Yes Canonical Routes asset key

Example request:

Request
curl -X PUT https://routes.srcry.xyz/v1/symbols \
  -H "Authorization: Bearer $ROUTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "symbols": [
    { "symbol": "ETH", "asset_key": "native.evm:1" },
    { "symbol": "USDC", "asset_key": "erc20.evm:1_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" },
    { "symbol": "BTC", "asset_key": "native.btc" },
    { "symbol": "ETH-BASE", "asset_key": "native.evm:8453" },
    { "symbol": "SOL", "asset_key": "native.solana" }
  ]
}'
Request
import httpx

response = httpx.put(
    "https://routes.srcry.xyz/v1/symbols",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "symbols": [
            {"symbol": "ETH", "asset_key": "native.evm:1"},
            {"symbol": "USDC", "asset_key": "erc20.evm:1_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"},
            {"symbol": "BTC", "asset_key": "native.btc"},
            {"symbol": "ETH-BASE", "asset_key": "native.evm:8453"},
            {"symbol": "SOL", "asset_key": "native.solana"},
        ],
    },
)
Request
const response = await fetch("https://routes.srcry.xyz/v1/symbols", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    symbols: [
      { symbol: "ETH", asset_key: "native.evm:1" },
      { symbol: "USDC", asset_key: "erc20.evm:1_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" },
      { symbol: "BTC", asset_key: "native.btc" },
      { symbol: "ETH-BASE", asset_key: "native.evm:8453" },
      { symbol: "SOL", asset_key: "native.solana" },
    ],
  }),
});
Request body
{
  "symbols": [
    { "symbol": "ETH", "asset_key": "native.evm:1" },
    { "symbol": "USDC", "asset_key": "erc20.evm:1_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" },
    { "symbol": "BTC", "asset_key": "native.btc" },
    { "symbol": "ETH-BASE", "asset_key": "native.evm:8453" },
    { "symbol": "SOL", "asset_key": "native.solana" }
  ]
}

Example response:

{
  "request_id": "req_01J...",
  "created": 5,
  "updated": 0,
  "unchanged": 0
}

Response fields

Field Type Description
request_id string Request identifier
created integer Number of new symbol mappings created
updated integer Number of existing symbol mappings updated
unchanged integer Number of mappings that were already identical

Bijection constraint

Each symbol maps to exactly one asset key, and each asset key maps to at most one symbol within your organization. Submitting a batch that violates this constraint is rejected atomically with a 409 symbol_conflict error.

// Fails with 409 symbol_conflict — two symbols point to the same asset_key
{
  "symbols": [
    { "symbol": "ETH", "asset_key": "native.evm:1" },
    { "symbol": "ETHEREUM", "asset_key": "native.evm:1" }
  ]
}

Case-insensitivity

Submitting a mapping for eth when ETH is already registered updates the stored casing and counts as updated.

GET /symbols

Use this to list all registered symbols for your organization.

Useful query parameters:

  • q — search filter
  • limit
  • cursor

Example response:

{
  "request_id": "req_01J...",
  "symbols": [
    {
      "symbol": "ETH",
      "asset_key": "native.evm:1",
      "created_at_ms": 1730000000000
    },
    {
      "symbol": "ETH-BASE",
      "asset_key": "native.evm:8453",
      "created_at_ms": 1730000000000
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Response fields

Field Type Description
request_id string Request identifier
symbols[].symbol string Partner-defined symbol
symbols[].asset_key string Canonical Routes asset key
symbols[].created_at_ms integer Symbol creation timestamp
has_more boolean More results available
next_cursor string Pagination cursor

DELETE /symbols/{symbol}

Use this to remove a single symbol mapping. The symbol in the path must be URL-encoded if it contains special characters.

Returns 204 on success, 404 if the symbol is not registered for this organization.

Example request:

Request
# Symbol "BASE:ETH" requires URL encoding of ":"
curl -X DELETE https://routes.srcry.xyz/v1/symbols/BASE%3AETH \
  -H "Authorization: Bearer $ROUTES_API_KEY"
Request
import httpx
from urllib.parse import quote

symbol = "BASE:ETH"
response = httpx.delete(
    f"https://routes.srcry.xyz/v1/symbols/{quote(symbol, safe='')}",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
)
Request
const symbol = "BASE:ETH";
const response = await fetch(
  `https://routes.srcry.xyz/v1/symbols/${encodeURIComponent(symbol)}`,
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
    },
  },
);

Error codes

Code HTTP Description
symbol_conflict 409 A symbol or asset_key uniqueness constraint was violated. The message field indicates whether the conflict is on the symbol or asset_key side.
invalid_symbol 400 Symbol does not match format constraints
symbol_not_found 404 Symbol is not registered for this organization