Tetrac API Documentation

JSON body

• publicKey (string)

  The account's Solana address (base58). Send this or email.

• email (string)

  The account email, for email sign-in. Send this or publicKey.

• appId (string)

  Optional. Must be "tetrac" when sent; that is also the default.

Success: 200

{
  "challenge": "<64 hex characters>",
  "pbkdf2Iterations": 600000
}

Errors

• 400 Neither publicKey nor email, or a malformed value.
• 429 Rate limit exceeded.

JSON body

• publicKey (string)required

  The wallet's Solana address (base58).

• signature (string)required

  Hex-encoded ed25519 signature of the message below, made by that wallet (a 0x prefix is accepted).

• challenge (string)required

  The challenge issued for this publicKey.

• appId (string)

  Optional. Must be "tetrac" when sent; that is also the default.

Signed message (UTF-8)

www.tetrac.xyz wants you to sign in with your Solana account:
<address>

Sign in to prove you own this wallet. This request does not send a transaction or cost any fees.

URI: https://www.tetrac.xyz
Version: 1
Nonce: <challenge>

Success: 200

{
  "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
  "authToken": "<64 hex characters>",
  "user": {
    "appId": "tetrac",
    "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
    "authMethod": "wallet",
    "wallets": [
      {
        "chain": "evm",
        "role": "funds",
        "publicKey": "0x1234…",
        "encryptedSecret": "<ciphertext>"
      }
    ],
    "createdAt": 1760000000000
  }
}

Errors

• 400 A field is missing or malformed.
• 401 Invalid credentials: a bad signature, or an expired or already-used challenge.
• 422 The wallet is not registered. Use connect-wallet or register.
• 429 Rate limit exceeded.

JSON body

• publicKey (string)required

  The wallet's Solana address (base58).

• signature (string)required

  Hex-encoded ed25519 signature of the message below, made by that wallet.

• challenge (string)required

  The challenge issued for this publicKey.

• wallets (array)

  Array of { chain, role, publicKey, encryptedSecret }, at most one per slot (solana/funds, solana/signing, evm/funds, evm/signing). encryptedSecret is ciphertext made in the browser under the account's app key (at most 8192 characters); the server stores it and cannot decrypt it. Stored only when the account is new or has no wallets yet.

• offchainEnvelope (string)

  Ledger accounts only: "legacy" or "v0", the off-chain message layout the device signed.

• appId (string)

  Optional. Must be "tetrac" when sent; that is also the default.

Signed message (UTF-8)

www.tetrac.xyz wants you to sign in with your Solana account:
<address>

Sign in to prove you own this wallet. This request does not send a transaction or cost any fees.

URI: https://www.tetrac.xyz
Version: 1
Nonce: <challenge>

Success: 201

{
  "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
  "authToken": "<64 hex characters>",
  "user": {
    "appId": "tetrac",
    "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
    "authMethod": "wallet",
    "wallets": [
      {
        "chain": "evm",
        "role": "funds",
        "publicKey": "0x1234…",
        "encryptedSecret": "<ciphertext>"
      }
    ],
    "createdAt": 1760000000000
  }
}

Errors

• 400 A field is missing or malformed.
• 401 Invalid credentials, including an email or passkey account that already uses this address.
• 429 Rate limit exceeded, including the deployment-wide limit on new accounts.

JSON body

• publicKey (string)required

  Solana address (base58) of the account's funds wallet. The challenge must have been issued for it.

• signature (string)required

  Hex-encoded ed25519 signature of the message below, made by that wallet's key.

• challenge (string)required

  The challenge issued for this publicKey.

• authMethod (string)

  "email" (the default), "wallet" or "biometric".

• authPublicKey (string)

  The account's ed25519 auth public key (64 hex characters), which email sign-in signatures are checked against. Required unless authMethod is "wallet".

• email (string)

  The account email.

• wallets (array)

  Array of { chain, role, publicKey, encryptedSecret }, at most one per slot (solana/funds, solana/signing, evm/funds, evm/signing). encryptedSecret is ciphertext made in the browser under the account's app key (at most 8192 characters); the server stores it and cannot decrypt it.

• pbkdf2Iterations (integer)

  Email accounts: the PBKDF2 iteration count (100000 to 1000000) the browser derived the app key with. It is pinned for every later sign-in.

• offchainEnvelope (string)

  Ledger accounts only: "legacy" or "v0".

• appId (string)

  Optional. Must be "tetrac" when sent; that is also the default.

Signed message (UTF-8)

www.tetrac.xyz wants you to sign in with your Solana account:
<address>

Sign in to prove you own this wallet. This request does not send a transaction or cost any fees.

URI: https://www.tetrac.xyz
Version: 1
Nonce: <challenge>

Success: 201

{
  "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
  "authToken": "<64 hex characters>",
  "user": {
    "appId": "tetrac",
    "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
    "authMethod": "wallet",
    "wallets": [
      {
        "chain": "evm",
        "role": "funds",
        "publicKey": "0x1234…",
        "encryptedSecret": "<ciphertext>"
      }
    ],
    "createdAt": 1760000000000
  }
}

Errors

• 400 A field is missing or malformed.
• 401 Signature verification failed, or the challenge is invalid or expired.
• 409 An account already exists for this address or email.
• 429 Rate limit exceeded, including the deployment-wide limit on new accounts.

JSON body

• email (string)required

  The account email.

• signature (string)required

  Hex-encoded ed25519 signature of the message below, made by the account's auth key (the key behind authPublicKey).

• challenge (string)required

  The challenge issued for this email.

• appId (string)

  Optional. Must be "tetrac" when sent; that is also the default.

Signed message (UTF-8)

Sign in to your TTC account: <challenge>

Success: 200

{
  "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
  "authToken": "<64 hex characters>",
  "user": {
    "appId": "tetrac",
    "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
    "authMethod": "email",
    "wallets": [
      {
        "chain": "evm",
        "role": "funds",
        "publicKey": "0x1234…",
        "encryptedSecret": "<ciphertext>"
      }
    ],
    "createdAt": 1760000000000
  }
}

Errors

• 400 A field is missing or malformed.
• 401 Invalid credentials.
• 429 Rate limit exceeded.

Headers

• ttc-auth-token (string)required

  The authToken from a sign-in response (64 hex characters, valid 24 h).

• ttc-public-key (string)required

  The publicKey from the same sign-in response.

Success: 200

{
  "ok": true
}

Errors

• 429 Rate limit exceeded.

Headers

• ttc-auth-token (string)required

  The authToken from a sign-in response (64 hex characters, valid 24 h).

• ttc-public-key (string)required

  The publicKey from the same sign-in response.

Success: 200

{
  "user": {
    "appId": "tetrac",
    "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
    "authMethod": "wallet",
    "wallets": [
      {
        "chain": "evm",
        "role": "funds",
        "publicKey": "0x1234…",
        "encryptedSecret": "<ciphertext>"
      }
    ],
    "createdAt": 1760000000000,
    "gateway_grant": false,
    "gateway_grant_symbol": null
  }
}

Errors

• 401 Missing, invalid or expired session.
• 429 Rate limit exceeded.

Headers

• ttc-auth-token (string)required

  The authToken from a sign-in response (64 hex characters, valid 24 h).

• ttc-public-key (string)required

  The publicKey from the same sign-in response.

JSON body

• preferenceKey (string)required

  "migration" or "user_participation_preferences".

• preferences (object)required

  The value to store, at most 4 KB as JSON. user_participation_preferences must be { leaderboard: boolean, dao: boolean, lastUpdated: string }.

Success: 200

{
  "success": true,
  "message": "Preferences updated successfully"
}

Errors

• 400 Unknown preferenceKey, a malformed value, or over 4 KB.
• 401 Invalid or expired session.
• 429 Rate limit exceeded.

Headers

• ttc-auth-token (string)required

  The authToken from a sign-in response (64 hex characters, valid 24 h).

• ttc-public-key (string)required

  The publicKey from the same sign-in response.

JSON body

• wallets (array)required

  Array of { chain, role, publicKey, encryptedSecret }, at most one per slot (solana/funds, solana/signing, evm/funds, evm/signing). encryptedSecret is ciphertext made in the browser under the account's app key (at most 8192 characters); the server stores it and cannot decrypt it. Each entry replaces the slot it names.

Success: 200

{
  "user": {
    "appId": "tetrac",
    "publicKey": "CgzKjTLrNgi9B6iCzLKfcLasYTuuEUibsei97qjmm7t5",
    "authMethod": "wallet",
    "wallets": [
      {
        "chain": "evm",
        "role": "funds",
        "publicKey": "0x1234…",
        "encryptedSecret": "<ciphertext>"
      }
    ],
    "createdAt": 1760000000000
  }
}

Errors

• 400 wallets is missing or malformed.
• 401 Missing, invalid or expired session.
• 429 Rate limit exceeded.

Query parameters

• publicKey (string)required

  The Solana address (base58) to look up.

• appId (string)

  Optional. Must be "tetrac" when sent; that is also the default.

Success: 200

{
  "exists": true
}

Errors

• 400 publicKey is missing or malformed.
• 429 Rate limit exceeded.

Response fields (200)

• success (boolean)
• status (string)
• code (integer)
• pricing (object)
• methods (object) — Keyed by method name; every entry is run with POST /api/v1/exchanges
• supportedExchanges (string[]) — Venue ids accepted as exchangeName by POST /api/v1/exchanges

Responses

• 200 Methods catalog, pricing summary and venue roster
• 400 A non-empty method query parameter was sent — this GET takes none; run methods with POST /api/v1/exchanges. Returned before any payment is taken.
• 402 Payment required (x402) — the body also carries methods, pricing and supportedExchanges
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

JSON body

• exchangeName (string)required

  Venue id from supportedExchanges, case-insensitive (normalised to lower case). Venue roster changes over time and is not enumerated here; the current list is returned by GET /api/v1/exchanges (including in its 402 discovery response, which requires no payment) and is shown on https://www.tetrac.xyz.

• method (string; one of setHedgeMode, setLeverage, getInfoLeverage, getPositions, getBalance, placeLimitOrder, placeMarketOrder, placeStopOrder, closeAllPositions, createWithdrawal, getDepositAddress, getOrders, cancelAllOrders, cancelOrder, getUserTradeHistory, getAccounts, getTickers, getBestBidAsk, getKlines, getContractSpecs)required

  One of the methods in the methods catalog from GET /api/v1/exchanges

• params (object | string)

  Method-specific parameters. getOrders, getBestBidAsk and cancelAllOrders also accept the bare symbol string.

• credentials (object)

  Exchange API credentials. Omit for the public market-data methods; getAccounts needs apiKey only; every other method needs apiKey and apiSecret.

  Fields: apiKey, apiSecret, passphrase, walletAddress

Response fields (200)

• success (boolean)
• data (any) — Method-shaped result
• code (integer)
• msg (string)
• exchange (string)

Responses

• 200 Method result
• 400 Bad input: the body is not a JSON object, exchangeName is missing or not a supported venue, method is not a supported exchange method, credentials are missing for a credentialed method, the method is not implemented on this venue, or the venue rejected the call. Every case except the venue rejecting the call is returned before any payment is taken.
• 402 Payment required (x402) — the body also carries methods, pricing and supportedExchanges
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Example request

POST https://www.tetrac.xyz/api/v1/exchanges
{
  "exchangeName": "binance",
  "method": "getTickers",
  "params": {}
}

Response fields (200)

• summary (object) — Aggregate counts and mean latency, split per probe type
• exchanges (ExchangeLatency[])
• timestamp (integer) — Epoch ms when the probe run completed

Responses

• 200 Per-exchange latency probe results plus aggregate summary
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Probe run failed

Response fields (200)

• success (boolean)
• status (string)
• code (integer)
• pricing (object)
• methods (object) — Keyed by sub-route slug, e.g. funding-rates

Responses

• 200 Endpoint catalog and pricing summary
• 429 Rate limit exceeded — retry after Retry-After seconds

Query parameters

• symbol (string)required

  Market symbol

• timeframe (string; one of 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M · default 1h)

  Binance USDⓈ-M futures kline interval (1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M; 1M is one month). Any other value returns 400 before payment.

• bars (integer; default 1000 · min 50 · max 1000)

  Number of historical bars to analyze, from 50. Defaults to 1000; larger values are clamped to 1000. Any other value returns 400 before payment.

• swingStrength (integer; default 10 · min 1 · max 100)

  Pivot sensitivity in bars, 1 to 100; higher values report only larger swings. Defaults to 10. Any other value returns 400 before payment.

Response fields (200)

• success (boolean)
• timestamp (integer)
• params (object)
• data (object)

Responses

• 200 Scanner result with signal
• 400 Missing or invalid query parameter, returned before any payment is taken
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected error, or fewer than 50 bars of history for the symbol (an unknown or newly listed market)

Example request

GET https://www.tetrac.xyz/api/v1/markets/ttc-scanner?symbol=BTCUSDT&timeframe=1h

Query parameters

• full (string; one of 0, 1)

  1 returns the full snapshot in data; 0 or omitted returns the freshness fields only. Any other value returns 400 before payment.

Response fields (200)

• success (boolean)
• timestamp (integer)
• generatedAt (integer) — Without full=1: epoch ms of the last sweep, null if none
• staleAtMs (integer) — Epoch ms when the snapshot becomes eligible for a refresh, or null if none exists yet
• data (object) — Only with full=1

Responses

• 200 Snapshot freshness, or the full snapshot with ?full=1
• 400 Invalid full value, returned before any payment is taken
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Query parameters

• type (string)

  Market type. Only futures is served; any other value is ignored and futures are returned.

• symbol (string)

  Exact symbol match (upper-cased before comparing).

• exchange (string)

  Keep only markets listed on this venue (matched against source and sources, case-insensitive).

• minimumVolume (number; min 0)

  Minimum 24h quote volume in USD (quoteVolume).

• minimumPrice (number; min 0)

  Minimum lastPrice. Swapped with maximumPrice if it is the larger of the two.

• maximumPrice (number; min 0)

  Maximum lastPrice.

• up (number; min -100 · max 10000)

  Keep markets whose 24h priceChangePercent is at least this value.

• down (number; min 0 · max 100)

  Keep markets down at least this many percent over 24h.

• health (string)

  Any value: return data = {status, redis, lastError, lastSuccessfulFetch, timeSinceLastFetch} (the ticker cache's health) instead of tickers.

Response fields (200)

• success (boolean)
• data (object)
• timestamp (integer)
• cached (boolean)
• cacheInfo (object)
• warning (string) — Optional advisory about the cache's state

Responses

• 200 Perpetual tickers
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Example request

GET https://www.tetrac.xyz/api/v1/markets/hybrid-tickers?exchange=binance&minimumVolume=10000000

Query parameters

• symbol (string)

  Only this symbol. Also widens the query to venues that have no bulk funding endpoint, which are skipped when no symbol is given; rows are then sorted by exchange.

• exchange (string)

  Comma-separated venue ids to keep (case-insensitive).

• arb (integer; min 1)

  Return only the N highest and N lowest fundingRate rows, sorted by fundingRate descending.

Response fields (200)

• success (boolean)
• data (FundingRate[])
• cached (boolean)
• timestamp (integer)
• error (string) — Present when some venues failed during the refresh

Responses

• 200 Funding rate data
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Query parameters

• source (string)

  Venue to read open interest from. An unsupported value falls back to bybit.

Response fields (200)

• success (boolean)
• data (OpenInterest[])
• timestamp (integer)
• source (string) — The venue the open interest came from

Responses

• 200 Open interest data
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected error, or the snapshot could not be fetched on a cold cache

Response fields (200)

• success (boolean)
• data (object)
• timestamp (integer) — Epoch ms of the response
• cached (boolean) — Always false; see data.cached

Responses

• 200 New listings
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Response fields (200)

• success (boolean)
• data (object)
• timestamp (integer)
• cached (boolean) — Always false; see data.cached

Responses

• 200 Screened tickers
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Response fields (200)

• success (boolean)
• items (NewsItem[])
• timestamp (integer)

Responses

• 200 News feed
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Query parameters

• currency (string)

  Comma-separated currency codes to keep (case-insensitive)

• impact (string; one of Low, Medium, High)

  Exact impact level (case-insensitive)

• search (string)

  Case-insensitive substring of event

• from (string; date)

  Earliest UTC date, inclusive

• to (string; date)

  Latest UTC date, inclusive

Response fields (200)

• success (boolean)
• data (object)
• timestamp (integer)
• cached (boolean) — Same as data.fromCache

Responses

• 200 Economic calendar events
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected error, or the calendar provider could not be paid or reached

Response fields (200)

• success (boolean)
• data (object[])

Responses

• 200 Daily volume history
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Query parameters

• exchange (string)

  Only this venue (exact id, case-insensitive)

Response fields (200)

• success (boolean)
• data (object[])
• cached (boolean)
• timestamp (integer)
• error (string) — Present when the refresh was degraded

Responses

• 200 Volume data
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Response fields (200)

• success (boolean)
• data (object)
• timestamp (integer)

Responses

• 200 USGS significant-earthquake feed
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Response fields (200)

• success (boolean)
• data (object)
• timestamp (integer)
• cached (boolean)

Responses

• 200 Symbol → venue membership map
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Unexpected server error

Query parameters

• venues (string)

  Comma-separated venue ids (case-insensitive) that rows and totals are narrowed to. Omit for every venue; the valid ids are the keys of venueStatus.

Response fields (200)

• fetchedAt (string)
• rows (object[])
• totals (object[])
• venueStatus (object)

Responses

• 200 Long/short and total open-interest rows per venue and symbol
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Snapshot collection failed

Example request

GET https://www.tetrac.xyz/api/v1/solana-perps/long-short?venues=pacifica

Query parameters

• limit (integer; default 250 · min 1 · max 1000)

  Number of accounts to return (parsed as an integer). Values above the maximum are capped; a non-positive or unparseable value falls back to the default.

Response fields (200)

• accounts (object[])
• totalRanked (integer)
• fetchedAt (string)

Responses

• 200 Ranked account watchlist
• 402 Payment required (x402)
• 429 Rate limit exceeded — retry after Retry-After seconds
• 500 Leaderboard fetch failed

Example request

GET https://www.tetrac.xyz/api/v1/solana-perps/pacifica-watchlist?limit=250