Get quote request

The quotes, sources and orders of one asset-pair POST /quotes answer. Required API-key scope: quotes_read. Immediate reads use the same held request handed to the asynchronous evidence writer; later reads recover its durable record. Readable by the principal that asked, by a member session allowed to view the workspace’s orders, and by an API key with the additional orders_read scope when an order was placed on one of its quotes in that workspace. Unknown and foreign ids are the same 404. A request lost in a crash before persistence returns 404 QUOTE_REQUEST_NOT_FOUND; its unpersisted quotes are also lost, so request fresh quotes. Genuine store or read failures return retryable 503 QUOTE_REQUEST_UNAVAILABLE with details.retryAfter and Retry-After. requestedByYou says whether the caller asked; only then can it order these quotes.

GET /api/v1/quotes/requests/{quoteRequestId}

Read a quote request's recorded answer

cURL

curl --request GET \
  --url https://api.tetrafi.io/api/v1/quotes/requests/{quoteRequestId} \
  --header 'X-API-Key: <api-key>'

200

{
  "orders": [
    {
      "orderId": "<string>",
      "quoteId": "<string>"
    }
  ],
  "quoteRequestId": "<string>",
  "quotes": [
    {
      "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
    }
  ],
  "request": {
    "buy": {
      "asset": "USDC",
      "chain": "eip155:8453"
    },
    "sell": {
      "asset": "USDC",
      "chain": "eip155:8453"
    },
    "buyAmount": "10000",
    "chosenWalletChains": [
      "eip155:8453"
    ],
    "deliverTo": {
      "financialAccountId": "<string>",
      "kind": "financialAccount"
    },
    "filters": {
      "firmOnly": true,
      "locations": [
        "singleChain"
      ],
      "modalities": [
        "amm"
      ],
      "variants": {
        "buy": "any",
        "sell": "any"
      },
      "venues": {
        "exclude": [
          "<string>"
        ],
        "include": [
          "<string>"
        ]
      }
    },
    "firmness": "indicative",
    "integrationAppId": "<string>",
    "onBehalfOf": "<string>",
    "preferredWallets": {},
    "priceProtectionBps": 1,
    "sellAmount": "10000",
    "sort": "netReceived",
    "source": {
      "fundingAccountId": "<string>",
      "tradingWallets": {},
      "venueAccountId": "<string>"
    },
    "timeout": "PT120S"
  },
  "requestedAt": "2023-11-07T05:31:56Z",
  "requestedByYou": true,
  "sources": [
    {
      "asked": true,
      "detail": "<string>",
      "status": "asking",
      "venue": {
        "id": "<string>",
        "logoUrl": "<string>",
        "modality": "amm",
        "name": "<string>",
        "protocolVersion": "<string>",
        "integrationMode": "basic",
        "venueId": "<string>",
        "venueName": "<string>"
      }
    }
  ],
  "venueAsked": true
}

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_read · api_key

quotes_read · 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).

Path Parameters

quoteRequestId · string · required

The set's quoteRequestId (rq_…)

Response

200

application/json

The recorded quote request

GET /quotes/requests/{quoteRequestId}: a quote request's recorded answer, read back by its owner. It carries no executable part.

orders · object[] · required

Every order placed on one of these quotes.

Show child attributes

quoteRequestId · string · required

quotes · object[] · required

A recorded card plus its current server-held state. Economics remain as served.

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
}

request · object · required

The request as it was sent, in the POST /quotes body shape (sell, buy, exactly one of sellAmount or buyAmount; funding and delivery by target id, never raw identity fields).

Show child attributes

requestedAt · string<date-time> · required

requestedByYou · boolean · required

Whether the caller is the principal that asked. Only that principal can order these quotes: another member (view_orders) or an orders_read key reads them, and each liveState is the hold as its owner sees it, never the reader's authority to order.

sources · object[] · required

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