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 onePOST 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.

