API reference
Generated from the machine-readable contract at /openapi/v1.yaml, the same file your tooling reads, so this page cannot drift from the wire. Synfin API v1.0.0.
Base URL & auth
All endpoints are under https://synfin.xyz. Keyed endpoints take your key
in the x-api-key header (or
Authorization: Bearer <key>). Get a key at
portal.synfin.xyz.
Every response carries x-synfin-api-version: 1 (the major) and
x-synfin-build (the deploy's short commit sha). Assert the major
and alert on an unexpected bump, a breaking wire change mints
/openapi/v2.yaml and bumps the header.
Endpoints
GET /api/quote key optional
Live cross-venue quote
| Parameter | In | Required | Description |
|---|---|---|---|
from | query | yes | Give-side token symbol. |
to | query | yes | Want-side token symbol. |
amount | query | yes | Give amount, a positive decimal. |
slippageBps | query | no | Max slippage in basis points (memo floor input). |
ref | query | no | Keyless soft attribution slug (the meta-router convention). Recorded for source visibility only; never changes the response and is stripped from the cache key. |
feeBps | query | no | Integrator fee in bps (0 to 10, the cap). The integrator keeps 100 percent of it (no revenue share): it settles as an independent leg to `feeRecipient`. KEYED ONLY; on the keyless path it is `400 missing_key`. Requires `feeRecipient`. |
feeRecipient | query | no | Canton party your integrator fee settles to. Keyed only. |
Try it:
curl "https://synfin.xyz/api/quote?from=CC&to=USDCx&amount=100"
Responses: 200 A quote. `clientFees`/`appliedSchema` present only for keyed callers. · 400 · 401 · 429 · 503
POST /api/app/plan
First-party (keyless) execution plan
Try it:
curl -X POST "https://synfin.xyz/api/app/plan" \
-H "content-type: application/json" \
-d '{"from":"CC","to":"USDCx","amount":"100","venueId":"tradecraft","takerParty":"yourparty::1220...","idempotencyKey":"a-stable-key"}' Responses: 200 An execution plan. · 400 · 409 · 429 · 500 · 503
POST /api/execute/plan keyed
Partner (keyed) execution plan
Try it:
curl -X POST "https://synfin.xyz/api/execute/plan" \
-H "content-type: application/json" \
-H "x-api-key: sk_live_..." \
-d '{"from":"CC","to":"USDCx","amount":"100","venueId":"tradecraft","takerParty":"yourparty::1220...","idempotencyKey":"a-stable-key"}' Responses: 200 An execution plan. · 400 · 401 · 409 · 429 · 500 · 502
GET /api/outcome
Swap outcome + real settlement id
| Parameter | In | Required | Description |
|---|---|---|---|
party | query | yes | The taker's Canton party ("<hint>::<fingerprint>"). |
since | query | yes | |
deadline | query | yes | The on-ledger executeBefore deadline. |
escrow | query | no | Optional wire tuple (escrow party) to disambiguate concurrent swaps. |
amount | query | no | |
minReceive | query | no | |
want | query | no |
Try it:
curl "https://synfin.xyz/api/outcome?party=VALUE&since=VALUE&deadline=VALUE"
Responses: 200 The classified outcome. · 400 · 429 · 500
GET /api/liveness
Venue liveness (server-side probe)
| Parameter | In | Required | Description |
|---|---|---|---|
venue | query | no | |
from | query | no | |
to | query | no |
Try it:
curl "https://synfin.xyz/api/liveness?venue=tradecraft&from=CC&to=USDCx"
Responses: 200 The liveness verdict. · 400 · 429 · 500
GET /api/status
Service status summary
Try it:
curl "https://synfin.xyz/api/status"
Responses: 200 The status summary.
Error codes
Every non-2xx response has the shape
{ error, code, action? }: error is human-readable,
code is the stable token you branch on, and
action (when present) tells you what to do next.
| code | HTTP | Meaning | Action |
|---|---|---|---|
bad_request | 400 | Malformed or missing parameters or body. | Fix the request per the `error` message. |
unknown_token | 400 | A token symbol is not recognized. | Use a supported symbol (the `error` lists them). |
missing_key | 400, 401 | The endpoint or feature requires an API key. | Get a free key at portal.synfin.xyz and send it as x-api-key. |
invalid_key | 401 | The API key is unrecognized or revoked. | Check the key, or create one at portal.synfin.xyz. |
rate_limited | 429 | The per-IP or per-key window was exceeded. | Back off until Retry-After; raise your plan limit in the portal. |
key_verification_unavailable | 503 | The key store is temporarily unreadable; the key may be valid. | Retry after Retry-After. |
unsupported_pair | 409 | The pair is not executable (e.g. no CC leg). | Re-quote a supported pair. |
venue_unavailable | 409 | The chosen venue is not currently executable. | Re-quote and choose an available venue. |
fee_unconfigured | 503 | A collecting B2C plan has no configured fee destination (internal fail-closed). | Internal; should never reach a keyed integrator. |
guardrail | 500 | A party-isolation guardrail tripped (internal). | Internal; contact support if seen. |
internal | 500, 502 | An unexpected server error. | Retry; if it persists, contact support. |
The full schemas (request/response bodies) live in the spec file itself: /openapi/v1.yaml. Point Swagger, Redoc, or your codegen at it directly.