GET /api/quote

Live cross-venue quotes, ranked by worst-case net receive after all fees. Public without a key; an API key adds your disclosed fee lines and higher limits, and never changes the ranking.

Parameters

param	required	type	meaning
`from`	yes	symbol	The asset you sell. Known symbols: `CC`, `USDCx`, `CBTC`.
`to`	yes	symbol	The asset you want.
`amount`	yes	decimal string	Positive, up to 1,000,000,000.
`slippageBps`	no	integer	Non-negative; default 50.
`feeBps`	keyed only	integer	Your integrator fee, 0 to 10 (the cap). Requires `feeRecipient`.
`feeRecipient`	keyed only	party id	Your Canton party (`hint::1220` plus 64 hex chars). Requires `feeBps`.

Keyed vs keyless

Keyless: full quotes, no fee params, a shared per-IP limit (rate limits). Response bytes are identical for everyone.
Keyed (x-api-key header or Authorization: Bearer): adds clientFees per available venue and the appliedSchema audit field, plus X-RateLimit-Limit and X-RateLimit-Remaining headers. Partners with negotiated terms see their own schema applied; appliedSchema.overrideId records it.

Response shape

field	meaning
`pair`	Canonical instrument names for the pair. `CC` resolves to its registry name `Amulet`.
`amount`, `asOf`	Echo of the request and the quote timestamp.
`venues[]`	One entry per integrated venue, always all of them.
`venues[].gross` / `net`	Headline output vs output after the venue's network fee.
`venues[].fee`	The venue network fee: `amount`, `asset`, and `appliedTo` (`on_top` or `deducted_from_give`). See fee semantics.
`venues[].available` / `rejectionCode`	A venue that cannot quote stays listed with its reason.
`venues[].clientFees`	Keyed only: `integrator` (bps, amount, recipient), `service` (bps, amount), `userReceives`.
`best`, `edgeBps`	The highest-net venue and its edge over the next, in bps.
`appliedSchema`	Keyed only: `schemaId` and `overrideId`, pinning the fee schema that produced the numbers.

Example

curl "https://synfin.xyz/api/quote?from=CC&to=USDCx&amount=100"

{
  "pair": {
    "give": "Amulet",
    "want": "USDCx"
  },
  "amount": "100",
  "asOf": "2026-07-03T16:23:07.850Z",
  "venues": [
    {
      "venueId": "tradecraft",
      "settlementMode": "managed-deposit",
      "available": true,
      "gross": "13.807171",
      "net": "13.807171",
      "fee": null,
      "feeBps": 0,
      "rejectionCode": null
    },
    {
      "venueId": "cantex",
      "settlementMode": "managed-deposit",
      "available": true,
      "gross": "13.773168",
      "net": "13.661566",
      "fee": {
        "amount": "0.8169",
        "asset": "Amulet",
        "appliedTo": "on_top"
      },
      "feeBps": 0,
      "rejectionCode": null
    },
    {
      "venueId": "oneswap",
      "settlementMode": "managed-deposit",
      "available": true,
      "gross": "12.702348",
      "net": "12.702348",
      "fee": {
        "amount": "8.7444230000",
        "asset": "Amulet",
        "appliedTo": "deducted_from_give"
      },
      "feeBps": 0,
      "rejectionCode": null
    },
    {
      "venueId": "nightly",
      "settlementMode": "managed-deposit",
      "available": false,
      "gross": null,
      "net": null,
      "fee": null,
      "feeBps": null,
      "rejectionCode": "invalid_request"
    }
  ],
  "best": {
    "venueId": "tradecraft",
    "gross": "13.807171",
    "net": "13.807171"
  },
  "edgeBps": 0
}

Captured from production 2026-07-03T16:23Z.

For a keyed example with clientFees, see the quickstart.

Caching

Successful responses carry Cache-Control: public, s-maxage=10: the edge caches the fee-free base body for about 10 seconds per parameter combination, shielding venues from per-visitor load while a refresh within seconds of a real pool move still reflects it. Keyed fee lines are computed per response and never shared through the cache. Errors are no-store.

Meta-routers and keyless volume

Pulling Synfin quotes into another aggregator is welcome. The stated path for programmatic volume is a free API key: keys cost nothing (over the limit blocks, never bills), raise your per-minute window, attribute your traffic so we can see and support your integration, and unlock the disclosed fee lines. Get one at portal.synfin.xyz.

Keyless works for evaluation and stays byte-identical, but it is metered per IP, and fresh parameter combinations (edge-cache misses) draw from a separate keyless fresh-quote budget (see rate limits): varying amount per request will hit it quickly by design.

Soft attribution convention: keyless callers SHOULD send ref=<your-slug> (lowercase letters, digits, hyphens; up to 32 chars) or a descriptive User-Agent. The ref tag is recorded for source visibility only: it never changes the response and is stripped from the cache key.

400 cases

Every body below was captured from production on 2026-07-03. Quote errors are { "error": "..." } with status 400.

cause	body
missing param	`{"error":"from, to, and amount are required query parameters"}`
unknown token	`{"error":"unknown token: known symbols are CC, USDCx, CBTC"}`
bad amount	`{"error":"amount must be a positive decimal"}`
bad slippage	`{"error":"slippageBps must be a non-negative integer"}`
fee params without a key	`{"error":"integrator fees require an API key"}`
only one fee param	`{"error":"feeBps and feeRecipient must be provided together"}`
fee over the cap	`{"error":"feeBps exceeds the cap of 10 bps"}`
bad recipient	`{"error":"feeRecipient must be a Canton party id (hint::1220 plus 64 hex chars)"}`

 
Auth and limit failures (401, 429, 503) are shared across endpoints: see
errors.