> ## Documentation Index
> Fetch the complete documentation index at: https://docs.totalis.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner webhooks

> Get sign-ups, positions, balances and account updates for your users pushed to your server, signed per Standard Webhooks: the events, their data, verification, delivery and replay.

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](https://www.standardwebhooks.com/), so any Standard Webhooks library verifies it.

## Set up

Email [founders@totalis.trade](mailto:founders@totalis.trade) with your HTTPS URL and the environment
(production or [staging](https://docs.totalis.trade/hyperliquid/build/staging.md)). Totalis registers it and sends you a signing secret once:
`whsec_` followed by 32 random bytes in base64. Store it like a password.

| Change | How |
| - | - |
| New URL | Email us. A new URL comes with a new secret; the old secret stops signing. |
| Test delivery | Ask us for a `ping`. |
| Stop | Email us. Undelivered events are dropped. |

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](#replay).

## Events

Each event is one `POST` with a JSON body:

```json theme={null}
{
  "id": "fill_48213345_7",
  "type": "position.opened",
  "created_at": "2026-11-12T15:04:05Z",
  "data": {}
}
```

| Field | Value |
| - | - |
| `id` | Stable per event, and the same on every retry. Dedupe on it. |
| `type` | One of the types below |
| `created_at` | When it happened: the block time for a fill or settlement, otherwise when Totalis recorded it. RFC 3339, UTC. |
| `data` | Depends on `type` |

| `type` | When | `data` |
| - | - | - |
| `account.created` | A wallet you admitted created its Totalis account | `wallet`, `created_at` |
| `position.opened` | A position opened with one of your [builder codes](https://docs.totalis.trade/hyperliquid/build/builder-codes.md) | A fill, `kind` `ACCEPT` |
| `position.claimed` | Such a position was claimed | A fill, `kind` `CLAIM`. `amount` is before the profit fee; the owner received `amount` − `fee`. |
| `position.sold_back` | Such a position was cashed out to the vault | A fill, `kind` `CASH_OUT` |
| `position.settled` | Such a position settled. A win's profit is claimed later; anything else pays out or closes at once. | A [settlement](#settlement) |
| `balance.updated` | The vault balance or wallet USDC of an account you admitted changed | A [balance](#balance) |
| `operation.updated` | An operation of an account you admitted changed status | `wallet`, `occurred_at`, and `payload`: the stream's [`OPERATION_UPDATED`](https://docs.totalis.trade/hyperliquid/api-reference/websocket/account#event) payload |
| `withdrawal.updated` | A withdrawal of such an account changed | `wallet`, `occurred_at`, and `payload`: the stream's [`WITHDRAWAL_UPDATED`](https://docs.totalis.trade/hyperliquid/api-reference/websocket/account#event) payload |
| `ping` | Totalis tested your webhook | `{}` |

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

```json theme={null}
{
  "kind": "ACCEPT",
  "wallet": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
  "position_id": "0x6f1d2c0e9b4a7d3f8e2b1c5a9d0e4f7b3a6c8d1e2f5a9b0c4d7e1f3a5b8c2d6e",
  "legs": [{ "outcome_id": "1209", "side": "YES" }],
  "amount": "5000000",
  "fee": "75000",
  "stake": "4925000",
  "payout": "12500000",
  "share_bps": 2000,
  "time": "2026-11-12T15:04:05Z",
  "block_number": 48213345,
  "log_index": 7,
  "transaction_hash": "0x9a1e5c7d3b2f4e6a8c0d1f3b5a7e9c2d4f6b8a0e1c3d5f7a9b2e4c6d8f0a1b3c"
}
```

| Field | Value |
| - | - |
| `kind` | `ACCEPT` (the position opened), `CLAIM` or `CASH_OUT` |
| `wallet` | The wallet that acted, lowercase hex |
| `position_id`, `legs` | The position and its legs |
| `amount` | The gross stake, claim or cash-out price. A claim's `amount` is before the profit fee. |
| `fee` | The fee this fill paid |
| `stake`, `payout` | The position's net stake and what it pays if every leg wins, fixed when it opened. On every fill, so a claim reads without its opening. |
| `share_bps` | Your [revenue share](https://docs.totalis.trade/hyperliquid/build/builder-codes.md#reports-and-payouts) on the fill's day, in basis points. `null` before your first terms. |
| `time`, `block_number`, `log_index`, `transaction_hash` | Where it happened on HyperEVM |

### Settlement

```json theme={null}
{
  "position_id": "0x6f1d2c0e9b4a7d3f8e2b1c5a9d0e4f7b3a6c8d1e2f5a9b0c4d7e1f3a5b8c2d6e",
  "owner": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
  "legs": [{ "outcome_id": "1209", "side": "YES" }],
  "settlement_kind": "WIN",
  "stake": "4925000",
  "payout": "12500000",
  "settled_amount": "12500000",
  "credited": "4925000",
  "claimable": "7575000",
  "claim_fee": "113625",
  "share_bps": 2000,
  "time": "2026-11-14T02:10:41Z",
  "block_number": 48390112,
  "log_index": 2,
  "transaction_hash": "0x2c4e6a8b0d1f3e5a7c9b2d4f6e8a0c1b3d5f7e9a2c4b6d8f0e1a3c5b7d9f2e4a"
}
```

| Field | Value |
| - | - |
| `position_id`, `legs` | The position and its legs |
| `owner` | The wallet it settled for |
| `settlement_kind` | `WIN`, `LOSS`, `PARTIAL` or `EARLY_LOST` |
| `stake`, `payout` | As on a fill |
| `settled_amount` | What the position settled for, gross |
| `credited` | What settlement paid into the owner's vault balance at once |
| `claimable` | Profit left to claim, gross. Only a `WIN` has any. |
| `claim_fee` | The fee the claims take from `claimable`, in total: `floor(claimable × fee_bps / 10000)` |
| `share_bps` | As on a fill |
| `time`, `block_number`, `log_index`, `transaction_hash` | Where it settled on HyperEVM |

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

| `settlement_kind` | `credited` | `claimable` |
| - | - | - |
| `WIN` | The stake | `settled_amount` − stake, paid by a later claim (`position.claimed`) less `claim_fee` |
| `PARTIAL` | `settled_amount` | `0`: nothing to claim |
| `LOSS`, `EARLY_LOST` | `0` | `0` |

### 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`](https://docs.totalis.trade/hyperliquid/api-reference/account/get-account-value) returns:

```json theme={null}
{
  "account": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
  "state": "CURRENT",
  "amount": "26886375",
  "block_number": "48390113",
  "wallet_usdc": "2000000",
  "vault_cash": "12425000",
  "run_off_cash": "0",
  "open_positions": 1,
  "open_cost": "5000000",
  "claimable_profit": "7461375",
  "checkpoint": { "block_number": "48390113", "projection_state": "CURRENT" }
}
```

| Field | Value |
| - | - |
| `account` | The account's wallet |
| `state` | `CURRENT`, or `UNKNOWN` when the value could not be read at one block. Then every amount is `null`: read it again with [`GET /v1/partner/accounts/{wallet}/account-value`](https://docs.totalis.trade/hyperliquid/api-reference/partners/get-user-account-value). When Totalis could not read the account at all, `checkpoint` is block `0`, `STALE`. |
| `amount` | The total of the five amounts below |
| `block_number` | The block every amount was read at |
| `wallet_usdc` | USDC in the wallet |
| `vault_cash` | The account's cash in the vault |
| `run_off_cash` | Its cash in vaults running off |
| `open_positions`, `open_cost` | Its open positions and what they cost |
| `claimable_profit` | Profit its settled wins can still claim, net of the claim fee |

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:

| Header | Value |
| - | - |
| `webhook-id` | The event's `id` |
| `webhook-timestamp` | Unix seconds when this attempt was signed |
| `webhook-signature` | `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}` |

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.

```ts theme={null}
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.TOTALIS_WEBHOOK_SECRET);

// rawBody is the request body exactly as received, before JSON parsing.
const event = webhook.verify(rawBody, {
  "webhook-id": headers["webhook-id"],
  "webhook-timestamp": headers["webhook-timestamp"],
  "webhook-signature": headers["webhook-signature"],
});
```

## Delivery

| Rule | Detail |
| - | - |
| Delivered | Any `2xx` within the [timeout](https://docs.totalis.trade/hyperliquid/limits-and-fees.md#partner-webhooks) |
| Failed | Any other status, a redirect, or no answer in time. Redirects are not followed. |
| Retried | On the [retry schedule](https://docs.totalis.trade/hyperliquid/limits-and-fees.md#partner-webhooks), then dropped |
| Duplicates | Possible. A repeat has the same `id`. |
| Order | None. Events of one position or account can arrive out of order: order them by `created_at`, or by block and log. |

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`](https://docs.totalis.trade/hyperliquid/api-reference/partners/list-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`.

```ts theme={null}
import { createPartnerServer } from "@totalis/hip4-client/partner";

const partner = createPartnerServer({ environment: "production", serverKey: process.env.TOTALIS_PARTNER_KEY });

let cursor = savedCursor; // the last next_cursor you processed, or undefined
for (;;) {
  const page = await partner.webhookEvents({ cursor, since: outageStart, limit: 200 });
  for (const item of page.events) await handle(item.event); // dedupe on item.event.id
  cursor = page.next_cursor ?? cursor;
  if (!page.has_more) break;
}
```

`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](https://docs.totalis.trade/hyperliquid/guides/realtime.md), 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`](https://docs.totalis.trade/hyperliquid/api-reference/partners/get-user-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`.

```ts theme={null}
const value = await partner.accountValue("0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be");
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.