Quickstart

1. Get a key

In the Totalis app, go to Account, then API keys, pick the taker scopes, and approve with your wallet. The key is shown once. A market maker issues its keys headless instead: Market making.

export TOTALIS_API_KEY="ttk_v1_prd_..."

An account whose own wallet signs in on a partner’s site issues its key from its wallet session instead (Create, rotate, revoke). For a frontend for your own users, or to test on testnet first, see Build on Totalis.

2. Read

Markets need no key:

curl "https://hip4-api.totalis.trade/v1/markets?limit=1"

{
  "items": [
    {
      "outcome_id": "1209",
      "native_question_id": null,
      "title": "HYPE touches 100 by 20261001-0000",
      "state": "ACTIVE",
      "sides": [
        { "side": "YES", "coin": "#12090" },
        { "side": "NO", "coin": "#12091" }
      ]
    }
  ],
  "next_cursor": "eyJnIjo2NDM3LCJhIjoxMjExLCJrIjoibWFya2V0In0",
  "has_more": true
}

The list is flat: one row per market, with no question title. Markets of one question share native_question_id. For a market in a question, Get market returns its question, with the title and all its markets. A standalone market has native_question_id: null and question: null. List questions (GET /v1/discovery) groups markets under their question titles, and lists standalone markets separately. Your identity checks the key:

curl https://hip4-api.totalis.trade/v1/me \
  -H "Authorization: Bearer $TOTALIS_API_KEY"

{
  "account_id": "0198a6f6-82a5-7abc-9f2a-4f0fb4374941",
  "status": "ACTIVE",
  "wallet": "0x1111111111111111111111111111111111111111"
}

wallet is your Totalis wallet. It signs your trades.

3. Request quotes

Subscribe to your account first, so no quote is missed:

wscat -c wss://hip4-ws.totalis.trade/v1/stream -s totalis.realtime.v2 \
  -H "Authorization: Bearer $TOTALIS_API_KEY"
> {"method":"subscribe","subscription":{"type":"account"}}

Then create an RFQ for 5 USDC on YES of outcome 1209:

curl https://hip4-api.totalis.trade/v1/rfqs \
  -H "Authorization: Bearer $TOTALIS_API_KEY" \
  -H "Idempotency-Key: 01a0df4e-5dc8-71f2-a3d4-c5b6a7988771" \
  -H "Content-Type: application/json" \
  -d '{ "stake": "5000000", "legs": [{ "outcome_id": "1209", "side": "YES" }] }'

{ "rfq_id": "01a0df4e-5e07-7a3c-8f21-d4e6b7a90c1a" }

Quotes arrive on the socket as QUOTE_CREATED, each with a payout. Generate a new lowercase UUIDv7 Idempotency-Key for every command.

4. Accept

Sign a quote and accept it before its accept_before: Trading.

Get started

Guides

Build on Totalis

TypeScript SDK

Resources

1. Get a key

2. Read

3. Request quotes

4. Accept

​1. Get a key

​2. Read

​3. Request quotes

​4. Accept

1. Get a key

2. Read

3. Request quotes

4. Accept