Request quotes

Ask every eligible venue for prices on one asset pair. kind selects the request body: pair for a new request, or requote to ask an earlier quote’s venue again (the new quote names it in requoteOf; the earlier quote stays held until it expires, and a requote more than 10 minutes after that expiry is 410 REQUOTE_WINDOW_CLOSED). A missing kind is 400 QUOTE_REQUEST_KIND_REQUIRED and an unknown one 400 QUOTE_REQUEST_KIND_INVALID. The answer is a PairQuoteSet: its quotes are held for you, and GET /quotes/requests/ reads it again. A request that asks a venue is limited to one every 3 seconds per caller (429 QUOTE_RATE_LIMITED with Retry-After). firmness is indicative, firm or auto (the default): indicative never asks a desk for a firm price, firm asks every eligible desk, and auto asks a production desk only when you name it in filters.venues.include or requote its card. Required API-key scope: quotes_request, on a key that also holds orders_write. A firm venue-account quote also needs workspace_venue_trade, the venue’s switch on for the key and request signing; without them the card is indicative, with sourceRefusal venueTradeScopeRequired. A key has no default wallet: name a trading wallet per chain in source.tradingWallets (CAIP-2 chain to financial-account id), either a workspace custody wallet or an organisation wallet granted to the key; a personal wallet is 409 PERSONAL_TARGET_NOT_ALLOWED. deliverTo is for member sessions only: a key’s requote naming one is 409 REQUOTE_REFUSED (details.reason deliverToNotPermitted). Every refusal uses the ApiError body.

POST /api/v1/quotes

Request quotes

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"
  },
  "kind": "pair",
  "sell": {
    "asset": "USDC",
    "chain": "eip155:8453"
  },
  "buyAmount": "10000",
  "chosenWalletChains": [
    "eip155:8453"
  ],
  "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": [],
  "sourceOptions": [],
  "sources": [
    {
      "asked": false,
      "detail": "This account is still being set up. Finish its activation in Venues before requesting prices.",
      "fix": {
        "kind": "manageVenueAccount",
        "step": "activate",
        "target": {
          "venueId": "selini"
        },
        "who": "manage_credentials"
      },
      "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 (enabled for the key in its workspace's credential settings, which return the signing secret once; see Sign requests) must also sign every request:

• X-Timestamp: the current Unix time in seconds, within 300 seconds of the server clock (at most 10 seconds ahead of it on a request that sends X-Nonce).
• X-Nonce: a fresh random value for each request, 16 to 128 characters of A-Z, a-z, 0-9, - and _ (a UUID fits). Required on a write (POST, PUT, PATCH, DELETE); optional on a read (GET, HEAD).
• 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 joined by \n, with no trailing newline: the X-Timestamp value, the X-Nonce 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 request without X-Nonce (a read) omits the nonce line and signs four lines.

A nonce is accepted once per key: the same nonce again inside the window is refused, whatever the body, so two identical writes in one second each carry their own nonce and both succeed, and a retry signs again with a new nonce. Every API server shares one nonce record, so a nonce accepted by one server is refused by all of them. Rate admission runs first: a rate-limited write (429) does not consume its nonce, and a replay sent while the key is rate limited is answered 429; otherwise a replay spends a rate token and is refused. A read without a nonce changes nothing, so an identical signed read inside the window is admitted again. A write whose window has already passed on the nonce record's clock when its nonce is recorded is refused as TIMESTAMP_OUT_OF_RANGE. If the nonce record cannot be read or written the request is refused with 503 API_KEY_UNAVAILABLE; the nonce may have been consumed, so sign again with a new X-Timestamp and X-Nonce before retrying.

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, NONCE_REQUIRED (a write without X-Nonce), NONCE_INVALID (a malformed or repeated X-Nonce header), SIGNATURE_REPLAYED (the nonce was already accepted). SIGNATURE_PREDATES_RESTART and 429 REPLAY_WINDOW_FULL are reserved and not answered today.

Scopes

quotes_request · api_key

quotes_request · bearer_auth

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. The required kind selects pair or requote; missing or unknown tags are refused with QUOTE_REQUEST_KIND_REQUIRED or QUOTE_REQUEST_KIND_INVALID before validating the selected payload.

buy · object · required

The Asset the taker buys, and optionally its chain.

Show child attributes

kind · enum<string> · required

Available options: pair

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"

chosenWalletChains · string[] | null

The chains whose preferredWallets entry the caller chose for this request itself (a trade ticket's Pay from or Receive in), rather than a saved default. Quoting reads every preferredWallets entry alike; this is recorded with the request and read back with it, so the request can be asked again from the same wallets on another device.

A CAIP-2 chain id (eip155:8453, solana:<genesis>, tron:shasta), syntax-checked: a namespace of 3 to 8 lowercase letters, digits or -, and a reference of 1 to 32 letters, digits, - or _. Compared exactly, as CAIP-2 references are case-sensitive.

deliverTo · object

Output to own money (a financial account) or an explicit chain address.

Option 1

Option 2

Show child attributes

filters · null | object

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

Show child attributes

firmness · null | enum<string>

Desk ask intent, independent of filters.firmOnly. Absent or auto preserves automatic pricing; indicative never firm-asks; firm asks every eligible desk.

Available options: indicative, firm, auto

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, referenceMid omitted and sourceOptions shown empty. 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. Core price, identity and progress facts are always present; venue-specific details are omitted when absent. Core timing fields that do not apply to the quote's firmness remain 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": [],
  "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": [
    {
      "execution": null,
      "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,
  "quality": "executable",
  "readiness": { "kind": "ready" },
  "screening": "screened",
  "sell": {
    "amount": "10000",
    "asset": "USDC",
    "chain": "eip155:42161",
    "variant": { "kind": "native", "name": "USDC" }
  },
  "signaturesRequired": 1,
  "sourceOptions": [],
  "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
indicative	the venue's price is shown without a firm-price ask; quoteId identifies the indicative card, whose firmAsk says whether the binding price comes on request or at execution
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