Stream prices

Server-sent snapshot events for each pair whenever its prices change.

GET /api/v1/prices/stream

Stream indicative prices

cURL

curl --request GET \
  --url https://api.tetrafi.io/api/v1/prices/stream \
  --header 'X-API-Key: <api-key>'

200

{
  "buy": "USDC",
  "computedAt": "2023-11-07T05:31:56Z",
  "referenceMid": {
    "buyPerSell": "<string>",
    "buyUsd": "<string>",
    "sellUsd": "<string>"
  },
  "rows": [
    {
      "status": "priced",
      "firm": true,
      "lastLook": true,
      "quality": "firm",
      "basis": "liveQuote",
      "blockNumber": 1,
      "buyVariant": {
        "kind": "native",
        "name": "<string>"
      },
      "ladderSemantics": "incremental",
      "levels": [
        {
          "price": "10000",
          "size": "10000"
        }
      ],
      "location": {
        "chain": "eip155:8453",
        "kind": "singleChain"
      },
      "observedAt": "2023-11-07T05:31:56Z",
      "sellVariant": {
        "kind": "native",
        "name": "<string>"
      },
      "sizes": [
        {
          "buy": "10000",
          "fees": [
            {
              "amount": "10000",
              "asset": "USDC",
              "chain": "eip155:8453",
              "included": true,
              "kind": "provider",
              "leg": 1,
              "paidBy": "taker",
              "bound": "maximum"
            }
          ],
          "filled": "full",
          "netReceived": {
            "amount": "10000",
            "kind": "known"
          },
          "sell": "10000",
          "feeObservedAt": "2023-11-07T05:31:56Z"
        }
      ],
      "spreadFromMidBps": {
        "bps": 123,
        "kind": "known"
      },
      "staleAfter": "2023-11-07T05:31:56Z",
      "venue": {
        "id": "<string>",
        "logoUrl": "<string>",
        "modality": "amm",
        "name": "<string>",
        "protocolVersion": "<string>",
        "integrationMode": "basic",
        "venueId": "<string>",
        "venueName": "<string>"
      }
    }
  ],
  "sell": "USDC",
  "sellBalances": [
    {
      "amount": "10000",
      "chain": "<string>",
      "observedAt": "2023-11-07T05:31:56Z",
      "state": "fresh"
    }
  ],
  "referenceMidUnavailable": "marketDataUnavailable"
}

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

prices_read · api_key

prices_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).

Query Parameters

pairs · string · required

1 to 25 comma-separated SELL:BUY Asset pairs (USDC:USDT,USDC:ZAR)

sellAmount · string

As GET /prices, applied to every pair

buyAmount · string

As GET /prices, applied to every pair

sizes · string

1 to 8 comma-separated positive sell amounts, applied to every pair; pairs × sizes at most 125

sell.chain · string

CAIP-2 pin for the sell side

buy.chain · string

CAIP-2 pin for the buy side

venues.include · string

Comma-separated venue ids to keep

venues.exclude · string

Comma-separated venue ids to drop

variants.sell · string

any | nativeOnly

variants.buy · string

any | nativeOnly

locations · string

Comma-separated singleChain, crossChain, offChain

modalities · string

Comma-separated amm, solver, bridge, rfq, orderBook, fiat

Response

200

text/event-stream

text/event-stream: a snapshot event (a GET /prices body for one pair) when that pair's rows change, a keep-alive comment every 15 s; the stream ends after 10 minutes

GET /prices 200, and each snapshot event of GET /prices/stream.

buy · string · required

A registry Asset id (USDC, USDe). Matched case-insensitively against the catalogue, which answers it in the registry's own spelling.

Example:

"USDC"

computedAt · string<date-time> · required

When the server built this snapshot (it reuses one for about a second).

referenceMid · null | object · required

The pair's indicative reference mid, from the same source as POST /quotes. null only when the read failed, with the cause in referenceMidUnavailable; never zero, stale or guessed. Never a quote input.

Show child attributes

rows · object[] · required

Sorted like quotes: netReceived at the first size descending, an unavailable value last, then by venue id (there is no best).

One venue's price for one location and variant pair.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Show child attributes

sell · string · required

A registry Asset id (USDC, USDe). Matched case-insensitively against the catalogue, which answers it in the registry's own spelling.

Example:

"USDC"

sellBalances · object[] · required

The sell Asset in the caller's own Default-binding wallets, one memory-only read per deployment (only the pinned chain when sell.chain is set). Display only, never a quote input. Empty for an API key, before the first warm, or with no bound wallet: unknown, never zero. A client totals the fresh entries and names every other entry as not read, never a silent partial total.

One chain's read of the sell Asset in the caller's Default-binding wallet.

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

Option 1

Option 2

Show child attributes

referenceMidUnavailable · null | enum<string>

Why referenceMid is null: marketDataUnavailable (a market-data refusal or outage), notPriced (no reference price exists for an asset) or timedOut (past the read's budget).

Available options: marketDataUnavailable, notPriced, timedOut