Skip to main content
Every authenticated request carries your API key. On REST and the quote streams, send it in the X-API-Key header. On the WebSocket, send it in the first message. Keys are scoped, so a key can read without being able to trade, and trade without being able to withdraw.

​
Getting your API key

1

Log in

Open app.totalis.trade and go to your account settings.
2

Create the key

Name it and choose its scopes. Grant only what this integration needs. The presets map to the scopes below: Read-only is the four read scopes, Trading adds trading:write and funds:deposit, and Custom lets you tick scopes one by one. The API also accepts a full preset. See Create API key.
The API Keys settings page with a key name, the Trading preset selected, and the read, trading and funds permissions checked

Creating a key with the Trading preset. Each checkbox is one scope from the catalog below.

3

Copy it immediately

The full key is returned exactly once, in data.key.
The API key generated successfully banner with the new api_live key, a copy button, and the note that it will not be shown again

The only time the full key is visible

Store the key in a secret manager before you close the dialog. It cannot be retrieved later, only revoked and replaced.
Keys match api_(live|test)_[A-Za-z0-9_-]{28,36}. Every key you create is a live key and starts api_live_. There is no public test environment. Start with small real bets, or email founders@totalis.trade if you need a staging setup.
The web app authenticates with a Privy JWT (Authorization: Bearer <jwt>) instead of a key. Every endpoint accepts either. Creating, listing and revoking keys needs keys:manage. A Privy session always holds it. A key holds it only if you granted it.

​
Using your API key

On the WebSocket, authenticate after connecting:
A credential that does not start with api_ gets 403 with reason wrong_api_key_type. A well-formed but invalid or revoked key gets 401. See Errors.

​
Scopes

A key holds the scopes you chose at creation. A request that needs a scope the key lacks gets 403 with reason insufficient_scope.
Each high-risk scope lets a leaked key take everything. funds:withdraw sends USDC to any address. tx:sign submits arbitrary transactions. keys:manage mints more keys, including ones that outlive your revocation of the original. Grant them only to keys that need them, and never to a key that lives in a browser or a CI log.
Scopes by integration:

​
Managing keys

{prefix} is the key_prefix value returned by both list and create: the short leading fragment that listings show in place of the full secret. The app shows each key’s prefix, scopes, request count and state, with a Revoke control on active keys.
Four API keys listed with their prefix, scopes, creation date, request count, and an active or revoked state

The key list in the app. Only the prefix of each key is ever shown again.

A new key can never grant a scope the creating credential does not already hold. A key with positions:read cannot mint a key with funds:withdraw.

​
Key states

Keys you create yourself never expire, so they reach the Expired state only if they were minted with an expiry. Revocation takes effect immediately. Revoking one key among several does not stop webhook delivery, because webhook endpoints belong to your account, not to the key that created them. See Webhooks.