Authentication

Private trading and account requests use long-lived, scoped tokens that you can revoke from the web app.

Creating a token

Sign in to the web app. (First-time only — after this you can stay in your terminal.)
Open Settings → API Tokens.
Click Create token, give it a label, choose scopes, and pick an optional expiration.
Copy the token right away. It's shown exactly once. If you lose it, revoke it and create a new one — there's no recovery.

A token looks like agt_ followed by 43 random characters:

agt_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhI

Using a token

Send it as a bearer credential on private trading and account requests:

Authorization: Bearer agt_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhI

Ordinary API-token requests need no timestamp or per-request HMAC. Market discovery, orderbooks, and the market stream are public and should omit this header. Pre-signed orders and account batches have separate signing rules.

Scopes

Each token carries a list of scopes set at creation. The platform enforces them; an out-of-scope request returns 403 with an error message naming the scope, e.g. forbidden scope: orders:place.

Scope	Grants
`portfolio:read`	Reading positions, open orders, fills, summary
`orders:read`	Reading individual order detail
`orders:place`	Placing new orders
`orders:place_signed`	Placing pre-signed orders (Agara, locally signed with your wallet key — see Pre-signed orders)
`orders:cancel`	Cancelling individual orders
`orders:cancel_all`	Cancelling everything open
`positions:split`	Splitting collateral into a complete binary pair on-chain
`positions:merge`	Merging a complete binary pair back into collateral on-chain
`batches:submit`	Submitting a wallet-signed account batch
`account:stream`	Receiving private order, fill, position, redemption, and collateral changes on the account-events WebSocket

Tokens can also be issued programmatically — see Create a personal access token.

Reading the orderbook doesn't require a scope — the GET /trade/v1/orderbook/{token_id} endpoint is public.

Recommended scope set for a trading bot:

portfolio:read
orders:read
orders:place
orders:cancel
orders:cancel_all
account:stream

If you only need read-only access (e.g. monitoring your positions), drop the three orders:* scopes that mutate.

What tokens can't do

The standard endpoints for these operations require a fresh browser session:

Withdrawing funds
Managing your tokens (creating, listing, revoking)

An account batch can contain a withdrawal only when it also carries the wallet's valid signature; an API token alone cannot create that signature. A leaked token can place trades on your behalf, but cannot use the standard withdrawal endpoint and cannot create replacement API tokens.

Revoking a token

Open Settings → API Tokens in the web app and click Revoke. The next request that uses that token gets 401 immediately — no grace period.

If you think a token is compromised:

Cancel any open orders first — use the same token (assuming it has orders:cancel_all) or the "Cancel all" button in the web app. Resting orders aren't auto-cancelled on revocation.
Then revoke the token.

TTL

Tokens don't expire unless you set an expires_at at creation. Set an expiry that matches your credential-rotation policy and replace the token before it lapses.