Skip to main content
Totalis posts events about your users to one HTTPS URL on your server: new accounts, positions opened, claimed, sold back and settled, balance changes with the account’s whole value, and operation and withdrawal updates. You stop polling for them. Delivery follows Standard Webhooks, so any Standard Webhooks library verifies it.

Set up

Email founders@totalis.trade with your HTTPS URL and the environment (production or staging). Totalis registers it and sends you a signing secret once: whsec_ followed by 32 random bytes in base64. Store it like a password. The URL must be https:// on a public address, with no credentials or fragment. You get events Totalis records while your webhook is set. Nothing from before is sent, though the first events can be from shortly before. Every event stays readable for 30 days: see Replay.

Events

Each event is one POST with a JSON body:
A position stays yours after it changes hands. New event types and new data fields can be added: ignore what you do not recognise.

Fill

Settlement

The owner receives credited + claimable − claim_fee in all, and every amount is known when the position settles:

Balance

balance.updated carries the account’s whole value at one HyperEVM block, read when Totalis sees the change, in the shape GET /v1/me/account-value returns:
Several changes close together can share one event. The highest block_number is the current value. Amounts are atomic USDC decimal strings, 6 decimals: "1500000" is 1.50 USDC. Wallets are lowercase hex.

Verify

Every request carries three headers: The HMAC key is the base64-decoded part of your secret after whsec_. Verify against the raw body bytes before you parse them, compare in constant time, and refuse a timestamp more than a few minutes from your clock. The header can list several space-separated signatures: accept the request if any one matches.

Delivery

Answer 2xx as soon as you have stored the event, and do the work after. A slow handler times out and is retried.

Replay

If your endpoint is down longer than the retries, read what you missed from your server with your partner server key: GET /v1/partner/webhook-events. It lists every event Totalis queued for you in the last 30 days, delivered or not, oldest first. Each item has the event exactly as it was posted, its delivery status (PENDING, DELIVERED or FAILED), attempts, queued_at and delivered_at.
next_cursor follows the last event even on the last page, so keep it and read again later for new events. A cursor never skips an event: one still being written appears after it. Handle each event as if it had been posted, and dedupe on its id.

Your users’ balances

balance.updated follows every change to an admitted account’s vault balance or wallet USDC, including a USDC transfer into or out of the wallet outside Totalis. For a live view of one account in a browser or app, use the account stream, which sends WALLET_BALANCE_CHANGED and VAULT_BALANCE_CHANGED. To read an admitted account’s value on demand, call GET /v1/partner/accounts/{wallet}/account-value from your server with your partner server key. It returns the same body as balance.updated and needs no key or session of the user’s, so it keeps working after theirs lapse. Use it for a first value when you start tracking a wallet, or to re-read one that arrived UNKNOWN. It reads only wallets you admitted that still sign for the account they opened. Any other wallet returns 404 NOT_FOUND.