Unified protocol and venue-account quote auction

The asset-pair contract (PairQuoteRequest or RequoteRequest); the legacy intent body is retired, so an object without `sell` or `requote` is 400 INVALID_REQUEST naming `sell`. Validated in order (INVALID_REQUEST naming the field, REQUOTE_FIELDS_CONFLICT, UNKNOWN_ASSET / UNKNOWN_CHAIN / UNKNOWN_VENUE naming the value, ASSET_NOT_ON_CHAIN (a side's Asset has no deployment on the chain pinned for it), INVALID_AMOUNT, SAME_ASSET_NEEDS_CHAIN, CHAIN_PIN_NEEDS_ON_CHAIN, out-of-range INVALID_REQUEST, ROUTING_OPTIONS_FORBIDDEN), then the request_quotes capability, and answered with a PairQuoteSet: every venue planned, venue-hitting plans limited to one every 3 s per principal (429 QUOTE_RATE_LIMITED with Retry-After; cache-only plans are not limited), quotes held for their owner and the set recorded for GET /quotes/requests/{quoteRequestId}. A requote body asks only the earlier quote's venue again (every venue of a multi-leg route, which answers that same route), as JSON (never a stream), and answers a PairQuoteSet whose one quote names it in requoteOf; the earlier quote stays held until its own expiry. Requote refusals: 400 CORRIDOR_NOT_OFFERED / WALLET_NOT_ON_CHAIN (a custody vault or registered workspace address bound to a chain it is not an account of; also on a fresh request), 403 SOURCE_NOT_OWNED / ACCOUNT_NOT_AVAILABLE / VENUE_NOT_AVAILABLE_TO_CREDENTIAL, 404 QUOTE_NOT_FOUND (unknown and another principal's quote alike), 409 REQUOTE_REFUSED (details.reason) / REQUOTE_NEEDS_WALLET / PERSONAL_TARGET_NOT_ALLOWED / QUOTE_CANNOT_BE_REFRESHED (a quote recorded before it could be refreshed for a broker's client), 410 REQUOTE_WINDOW_CLOSED (10 minutes after its expiry, past retainUntil; next search: request quotes again), 429 QUOTE_RATE_LIMITED / VENUE_FIRM_QUOTE_LIMITED /BUDGET_EXHAUSTED with Retry-After, 503 QUOTE_STORE_UNAVAILABLE / QUOTE_NOT_READY, 504 REQUOTE_TIMED_OUT. Every refusal, at every status, is the one error body ApiError {error, message, requestId, timestamp, next?, details?}. Optional filters narrow the auction. Orderable venue-account cards require a current MFA human Company/Broker session, or an API key holding workspace_venue_trade with its venue switch enabled and HMAC request signing. A member key with quotes_request but no venue-trading authority receives native indicative cards (firm false, expiresAt null) with sourceRefusal venueTradeScopeRequired and a re-issuance remedy, without any firm ask. On-chain sources without an organisation wallet grant are indicative with sourceRefusal onchainWalletNotUsable and a wallet-grant remedy; no signer is resolved. Quote-only observations never spend firm-quote budget, and their held refusal is returned if ordered. An API key quotes with quotes_request (which needs orders_write on the same key); it has no Default wallet of a member, so it binds a workspace wallet in bind.wallets: a workspace custody wallet, or an organisation wallet the key was granted (without that grant the source reads API_KEY_ORGANISATION_WALLET_SCOPE_REQUIRED), never a personal one (409 PERSONAL_TARGET_NOT_ALLOWED); its protocol venues remain non-orderable until it binds one; quote-only observations may show a native indicative price without borrowing a wallet. A desk on a production site is firm-asked only on request, the same for sessions and API keys, each one call: name it in filters.venues.include and its firm quote returns in that response, or requote its indicative card ({requote: quoteId}). A broad request never asks it: its card stays indicative and reads unavailable priceOnRequest when it publishes no price. Its next is requote, except where its firm quote lives 5 s or less: then it is order (execute within my limit), and that order makes the one ask, trading only at or above the person's minReceive; a requote of that card (Get firm quote) also asks it once under the same desk limits and returns a firm, executable card with its expiresAt. A sandbox or testnet desk that publishes nothing is firm-asked on a person's or API caller's request within the desk limits (firmQuoteLimited with retryAfter when they are reached); automation principals get it on requote only. On a venue-account card, bind.deliverTo {kind: address, chain, address, destinationTag?} names where the trade's output is withdrawn when the order for it fills: one of the workspace's own wallets that is an approved withdrawal destination of that venue account, for the receipt asset, with exactly that destination tag or memo. The card then carries that deliverTo, a network fee line for the venue's withdrawal fee (the most the order will pay; a higher fee at send refuses) and a receive net of it (netReceived unavailable withdrawalFeeUnread when the fee could not be read), and a requote keeps it. A venue that cannot deliver there answers its source unavailable with DESTINATION_NOT_APPROVED, DELIVER_TO_NOT_A_WORKSPACE_WALLET, WITHDRAWAL_CHAIN_UNSUPPORTED (no withdrawal network for that chain on the site; test sites have none), DELIVER_TO_AMBIGUOUS, WITHDRAWAL_FEE_EXCEEDS_AMOUNT, deliverToCalldataUnsupported or deliverToNotPermitted (deliverTo needs a member session with ViewWallets; an API key lists no deliverTo candidates, and a requote naming one answers 409 REQUOTE_REFUSED with details.reason deliverToNotPermitted). The request spends one Quote token; connection indicative pacing is reported on cards.

POST /api/v1/quotes

Unified protocol and venue-account quote auction

cURL

curl --request POST \
  --url https://api.tetrafi.io/api/v1/quotes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "buy": {
    "asset": "USDC",
    "chain": "eip155:8453"
  },
  "sell": {
    "asset": "USDC",
    "chain": "eip155:8453"
  },
  "buyAmount": "10000",
  "deliverTo": {
    "financialAccountId": "<string>",
    "kind": "financialAccount"
  },
  "filters": {
    "firmOnly": true,
    "locations": [],
    "modalities": [],
    "variants": {},
    "venues": {
      "exclude": [
        "<string>"
      ],
      "include": [
        "<string>"
      ]
    }
  },
  "integrationAppId": "<string>",
  "onBehalfOf": "<string>",
  "preferredWallets": {},
  "priceProtectionBps": 1,
  "sellAmount": "10000",
  "source": {
    "fundingAccountId": "<string>",
    "tradingWallets": {},
    "venueAccountId": "<string>"
  },
  "timeout": "PT120S"
}
'

200

{
  "quoteRequestId": "rq_01M5Z6TX3X834KT79RBP6X6FQB",
  "quotes": [],
  "sources": [
    {
      "asked": false,
      "detail": "This account is still being set up. Complete its required activation steps in Treasury before requesting prices.",
      "reason": "accountSetupIncomplete",
      "status": "unavailable",
      "venue": {
        "id": "selini-rfq",
        "integrationMode": "basic",
        "logoUrl": null,
        "modality": "rfq",
        "name": "Selini Capital",
        "protocolVersion": null,
        "venueId": "selini",
        "venueName": "Selini"
      }
    }
  ],
  "venueAsked": false
}

Authorizations

api_keybearer_auth

X-API-Key · string · header · required

Send the API key in X-API-Key.

Request signing. A key with signing enabled (POST /api/v1/workspaces/{workspaceId}/users/me/api-keys/{keyId}/signing, which returns the signing secret once) must also sign every request:

• X-Timestamp: the current Unix time in seconds, within 300 seconds of the server clock.
• X-Signature: lower-case hex HMAC-SHA256 of the canonical string, keyed with the signing secret's 32 bytes (the secret is 64 hex characters; decode it first).

The canonical string is four lines joined by \n, with no trailing newline: the X-Timestamp value, the upper-case method, the path with its query exactly as sent (/api/v1/orders?limit=1), and the lower-case hex SHA-256 of the exact body bytes (the SHA-256 of an empty body when there is none).

A write's signature (POST, PUT, PATCH, DELETE) is accepted once: sending the same signed write again is refused, so a retry signs again. A read (GET, HEAD) changes nothing, so an identical signed read inside the window is admitted again and polling needs no nonce.

A signing refusal is a 401 AUTH_REQUIRED whose details.reason names the cause: SIGNATURE_REQUIRED (a header is missing), SIGNATURE_INVALID (a malformed header or a wrong signature), TIMESTAMP_OUT_OF_RANGE or SIGNATURE_REPLAYED.

Headers

X-Workspace-Id · string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Body

application/json

Option 1

Option 2

The POST /quotes request body, told apart by shape: a top-level requote is a Requote; any other object is a pair request (the legacy intent body is retired).

buy · object · required

The Asset the taker buys, and optionally its chain.

Show child attributes

sell · object · required

The Asset the taker sells, and optionally its chain.

Show child attributes

buyAmount · null | string

The exact amount to buy, a positive decimal string in Asset units. Exactly one of sellAmount and buyAmount.

Example:

"10000"

deliverTo · object

Output to own money, a third-party payee, or an explicit chain address.

New values may be added; treat unknown values as other.

Option 1

Option 2

Option 3

Show child attributes

filters · null | object

The public request's narrowing filters; an omitted filter means all.

Show child attributes

integrationAppId · string | null

onBehalfOf · string | null

The direct user a broker quotes for.

preferredWallets · object | null

Per CAIP-2 chain: a wallet the caller prefers to sell from, by target id or address. A preference, not a choice: a venue account uses it only where it is one of that account's linked wallets on the venue's network, and otherwise quotes from its own default; a venue is never refused because of it. source.tradingWallets is the explicit choice and wins on its chain.

Show child attributes

priceProtectionBps · integer<int32> | null

The bound between a non-firm executable quote and what execution delivers.

Required range: x >= 0

sellAmount · null | string

The exact amount to sell, a positive decimal string in Asset units. Exactly one of sellAmount and buyAmount (400 INVALID_REQUEST naming both otherwise).

Example:

"10000"

sort · null | enum<string>

Default netReceived.

Available options: netReceived, eta

source · null | object

An explicit request choice. Every value is a financial-account id.

Show child attributes

timeout · null | string<duration>

Collection deadline, an ISO 8601 duration; default PT6S, at least 100 milliseconds and at most PT10S.

Pattern: ^PT(?:[0-9]+H(?:[0-9]+M)?(?:[0-9]+(?:\.[0-9]{1,3})?S)?|[0-9]+M(?:[0-9]+(?:\.[0-9]{1,3})?S)?|[0-9]+(?:\.[0-9]{1,3})?S)$

Example:

"PT120S"

Response

200

application/json

Quotes aggregated successfully: a PairQuoteSet. Accept: text/event-stream selects JSON-data SSE events: quote (PairQuote), source (QuoteSourceEntry), complete (PairQuoteSet), error. A venue the workspace's LP relationship does not allow reads restricted venueRelationship with neutral words in detail and is never asked. Event IDs increase monotonically; the stream includes keepalive comments. Example: broad USD 25000 to USDC, Selini source unavailable accountSetupIncomplete and asked=false; captured live (rfq 2ef31a1ea), one of twelve sources retained and referenceMid omitted. No Selini price or firm ask is implied; Selini USD settlement precision is six decimal places.

POST /quotes 200 body: the quote set. Schema only.

quoteRequestId · string · required

The quote set's id (rq_…), read back at GET /quotes/requests/{quoteRequestId}. The HTTP request id is separate (X-Request-Id, an error body's requestId).

quotes · object[] · required

One venue's quote for the pair. Every field is always present; one that does not apply to the quote's firmness is null:

field	indicative	executable, firm	executable, non-firm
firm	false	true	false
expiresAt	null	set	set
minOut	null	null	set
observedAt, staleAfter	set	null	null

A stub (sources[].priceOnRequest) is indicative with null amounts.

The example is an executable non-firm quote: 10000 USDC paid, buy.amount 9996.0 USDT lands after the included 4.0 USDT provider fee; netReceived 9994.8 also subtracts the 0.0004 ETH network fee the taker pays separately (included: false, about 1.2 USDT at the Reference mid), so it is lower than buy.amount; minOut 9966.01 (30 bps) bounds buy.amount, not netReceived.

Option 1

Option 2

Show child attributes

Example:

{
  "advisories": [],
  "assurance": null,
  "basis": "liveQuote",
  "buy": {
    "amount": "9996.0",
    "asset": "USDT",
    "chain": "eip155:8453",
    "variant": { "kind": "native", "name": "USDT" }
  },
  "corridors": [{ "from": "eip155:1", "to": "eip155:8453" }],
  "eta": "PT40S",
  "expiresAt": "2026-10-17T10:01:00Z",
  "failureHandling": "refundOnSource",
  "fees": [
    {
      "amount": "4.0",
      "asset": "USDT",
      "chain": null,
      "included": true,
      "kind": "provider",
      "leg": 0,
      "paidBy": "taker"
    },
    {
      "amount": "0.0004",
      "asset": "ETH",
      "chain": "eip155:42161",
      "included": false,
      "kind": "network",
      "leg": 0,
      "paidBy": "taker"
    }
  ],
  "firm": false,
  "id": "q_01JAY7Q5M3ZK8V2N4R6T8W0XYB",
  "lastLook": false,
  "legs": [
    {
      "expectedArrival": null,
      "fundingModel": null,
      "location": {
        "from": "eip155:42161",
        "kind": "crossChain",
        "to": "eip155:8453"
      },
      "venue": {
        "id": "tetrafi-solver",
        "logoUrl": null,
        "modality": "solver",
        "name": "TetraFi Solver",
        "protocolVersion": null
      }
    }
  ],
  "location": { "kind": "crossChain" },
  "minOut": "9966.01",
  "minReceiveRequired": false,
  "netReceived": { "amount": "9994.8", "kind": "known" },
  "next": { "kind": "sign", "typedData": {} },
  "observedAt": null,
  "readiness": { "kind": "ready" },
  "requoteOf": null,
  "screening": "screened",
  "sell": {
    "amount": "10000",
    "asset": "USDC",
    "chain": "eip155:42161",
    "variant": { "kind": "native", "name": "USDC" }
  },
  "signaturesRequired": 1,
  "spreadFromMidBps": { "bps": 6, "kind": "known" },
  "staleAfter": null
}

sourceOptions · object[] · required

The trading wallets this caller may name in source.tradingWallets, per network: each one's stored financial account (acct_…), scoped to the principal (an API key sees only the organisation wallets granted to it). Sent even when no card was priced, so an unbound request learns what to bind. Empty when none is usable.

New values may be added; treat unknown values as other.

Option 1

Option 2

Option 3

Option 4

Show child attributes

sources · object[] · required

Every considered venue, with its outcome.

One considered venue's outcome, a closed set tagged status:

status	meaning
asking	in flight on the stream only: the auction is consulting this venue now; its final outcome replaces it under the same venue key, and none remains at complete
answered	the venue produced a quote
needsWallet	no wallet of family to ask with
walletRefused	the bound wallet is refused (Revoked, a confirmed sanctions hit)
firmQuoteLimited	a desk's firm-quote cap applies; explanation is product copy
priceOnRequest	no venue price was requested; quoteId identifies the held estimate or stub to Requote
askLimitReached	the venue's ask limit is reached for now; retryAfter says when to ask again
timedOut	no answer inside the deadline
refused	the venue refused the live ask
restricted	a gate kept the venue from this principal
unsupported	the venue does not serve the pair
filteredOut	the request's own filters exclude it (never a coverage or chain gap)
unavailable	a read failed (admissionUnavailable, …)

An unscreened default wallet is not a status: the quote carries screening. venue is the venue block, its id the one quote legs and /prices rows carry. Durations (retryAfter) are ISO 8601, counted from when the response was sent. Every entry carries asked: whether this venue was consulted for this request: a live ask, or a fresh read of its published book or live desk price within that source's freshness window. An estimate no venue gave (a model or reference price) is not consulted, and an answered entry is always consulted. How a card's price was obtained is its own price basis, never this flag.

New values may be added; treat unknown values as other.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Show child attributes

venueAsked · boolean · required

Whether answering this request contacted any venue (a live or firm ask), always sent; false when every quote came from cache.

referenceMid · null | object

The Reference mid this request's cards were priced against, read once per request. Absent when the read failed or ran past its budget: the cards then read noReferenceMid, never a spread of 0.

Show child attributes