> ## 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. # Get partner report > Your partner's fees by UTC day for one range, with your terms, what you have earned, been paid and are owed, and every payout to you, as Totalis pays from them. Requires your partner server key (`tpk_`), sent from your server with no `Origin`; an API key cannot call it. ## OpenAPI ````yaml /hyperliquid/openapi.json get /v1/partner/report openapi: 3.1.1 info: title: Totalis Hyperliquid API description: >- REST API for Totalis singles and parlays on Hyperliquid HIP-4 outcome markets, for client integrations and external market makers. There are three ways in, each sent as `Authorization: Bearer `: - **Scoped API key** (`ttk_`), for servers, bots and market makers. The account owner creates it in the Totalis app, or a wallet-session user creates one with `POST /v1/me/api-keys` and a fresh wallet signature (see API keys). It acts for one account, yours or a maker's, with only the scopes it holds, and needs no `Origin`. - **Wallet session**, for users who bring their own wallet to a partner's web page. The page signs the wallet in with `POST /v1/auth/wallet-challenges` and `POST /v1/auth/wallet-sessions`; the session is bound to the page's registered `Origin` and must be sent from it. Pages may also label their traffic with their publishable browser key in `X-Totalis-Partner: tpb_...`. - **Partner server key** (`tpk_`), only for `POST /v1/partner/wallet-admissions`, which lets a new wallet open its account during the invite-only launch, and `GET /v1/partner/report`, your fees, terms and payouts. Server to server, never in a browser, and never with an `Origin`. Public market reads need no credential. A credential only authenticates: every bet, cash-out and withdrawal also carries the wallet or maker signature the HyperEVM contract verifies. An external wallet sends `POST /v1/core-exits` to move its vault cash to HyperCore before a HyperCore order. For access, partner credentials (origins, browser and server keys), builder codes or staging, email [founders@totalis.trade](mailto:founders@totalis.trade). Amounts are base-10 strings in native USDC atomic units, large identifiers are decimal strings, and every command `POST` requires an `Idempotency-Key` header. Every error is `{error: {code, message, retry, request_id, field_violations}}`. `code` is stable; each operation lists the codes it returns per status. `retry` is `NEVER` (stop), `BACKOFF` (resend the same request with the same `Idempotency-Key` after `Retry-After` seconds) or `REFRESH` (re-read state, then send a new request with a new key). `field_violations` names invalid inputs by JSON pointer, such as `/legs/0/side`. version: 181.0.0-partner-report servers: - url: https://hip4-api.totalis.trade description: Production public edge - url: https://hip4-api-staging.totalis.trade description: Staging and chain-998 public edge security: [] tags: - name: Markets description: >- HIP-4 questions and markets, their sides and price history. No API key needed. - name: RFQs & Quotes description: >- RFQs and the quotes that answer them: what a taker calls, then what a maker calls. - name: Positions description: Positions the account holds, or its maker backs. - name: Account description: >- The account a key acts for: identity, balances, activity, operations, withdrawals, deposits and HyperCore exits. - name: Makers description: >- The rest of a maker's setup after Making: admission, quote history, capital and collateral. - name: Partners & wallet sign-in description: >- A partner admits its users' own wallets, which sign in from the partner's pages, and reads its own report. - name: API keys description: >- Issue, rotate and revoke scoped keys from a wallet session. An API key cannot manage keys. - name: Deployment description: The contract deployment every signature is made against. - name: WebSocket description: The authenticated WebSocket for account and maker updates. paths: /v1/partner/report: get: tags: - Partners & wallet sign-in summary: Get partner report description: >- Your partner's fees by UTC day for one range, with your terms, what you have earned, been paid and are owed, and every payout to you, as Totalis pays from them. Requires your partner server key (`tpk_`), sent from your server with no `Origin`; an API key cannot call it. operationId: getPartnerReport parameters: - name: from in: query required: false schema: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: >- First UTC day of the range, inclusive. Send from and to together, at most 366 days apart; omit both for the 30 days through today. example: '2026-10-01' - name: to in: query required: false schema: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: >- UTC day after the range, exclusive: `from=2026-10-01&to=2026-11-01` is October. example: '2026-11-01' responses: '200': description: >- Your report. Balance, terms and payouts are all time; days and totals cover the range. No caching. content: application/json: schema: $ref: '#/components/schemas/PartnerReport' example: partner: acme as_of: '2026-11-03T09:00:00Z' balance: share_bps: 2000 fees: '412500000' unpriced_fees: '0' accrued: '82500000' paid: '60000000' owed: '22500000' terms: - effective_from: '2026-10-01' share_bps: 2000 from: '2026-10-01' to: '2026-11-01' totals: tickets: 214 stake_volume: '21400000000' taker_fees: '321000000' winnings_fees: '61500000' buyback_fees: '30000000' total_fees: '412500000' days: - day: '2026-10-01' share_bps: 2000 tickets: 120 stake_volume: '12000000000' taker_fees: '180000000' winnings_fees: '40000000' buyback_fees: '20000000' total_fees: '240000000' - day: '2026-10-02' share_bps: 2000 tickets: 94 stake_volume: '9400000000' taker_fees: '141000000' winnings_fees: '21500000' buyback_fees: '10000000' total_fees: '172500000' payouts: - payout_id: 019a3c4e-8f00-7000-8000-000000000001 period_start: '2026-10-01' period_end: '2026-10-31' payout_address: '0x1111111111111111111111111111111111111111' amount: '60000000' counted: '60000000' state: SETTLED queued_at: '2026-11-02T15:00:00Z' closed_at: '2026-11-02T15:06:00Z' transfers: - transaction_hash: >- 0x2222222222222222222222222222222222222222222222222222222222222222 outcome: LANDED moved: '60000000' recorded_at: '2026-11-02T15:01:00Z' resolved_at: '2026-11-02T15:06:00Z' '400': description: >- `INVALID_QUERY`: from or to is not a YYYY-MM-DD date, only one was sent, from is not before to, or they are more than 366 days apart. - `INVALID_QUERY` (retry `NEVER`): A query parameter is malformed, out of range or not accepted by this operation. `field_violations` names it. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: description: The error this operation returns with this status. properties: code: description: >- One of the registered codes listed in this response's description. enum: - INVALID_QUERY retry: description: >- The retry rule the registry fixes for the returned code. enum: - NEVER '401': description: >- The partner server key is missing, unknown or revoked, or your partner is suspended. - `UNAUTHENTICATED` (retry `NEVER`): The credential is missing, invalid, expired or revoked. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: description: The error this operation returns with this status. properties: code: description: >- One of the registered codes listed in this response's description. enum: - UNAUTHENTICATED retry: description: >- The retry rule the registry fixes for the returned code. enum: - NEVER '403': description: >- Any credential but a partner server key, or any request with an `Origin`, is refused: read reports from your server. - `FORBIDDEN` (retry `NEVER`): The credential is valid but lacks the scope, permission or role this operation needs. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: description: The error this operation returns with this status. properties: code: description: >- One of the registered codes listed in this response's description. enum: - FORBIDDEN retry: description: >- The retry rule the registry fixes for the returned code. enum: - NEVER '429': description: >- - `RATE_LIMITED` (retry `BACKOFF`): The request quota for this credential or route is exhausted. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: description: The error this operation returns with this status. properties: code: description: >- One of the registered codes listed in this response's description. enum: - RATE_LIMITED retry: description: >- The retry rule the registry fixes for the returned code. enum: - BACKOFF '503': description: >- The report is temporarily unavailable; resend after `Retry-After`. - `AUTHORIZATION_UNAVAILABLE` (retry `BACKOFF`): Identity or credential authority storage is unavailable. - `SOURCE_UNAVAILABLE` (retry `BACKOFF`): The account-read or stream source is unavailable. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: description: The error this operation returns with this status. properties: code: description: >- One of the registered codes listed in this response's description. enum: - AUTHORIZATION_UNAVAILABLE - SOURCE_UNAVAILABLE retry: description: >- The retry rule the registry fixes for the returned code. enum: - BACKOFF security: - partnerServerKey: [] components: schemas: PartnerReport: type: object required: - partner - as_of - balance - terms - from - to - totals - days - payouts description: >- A partner's own report: the figures Totalis pays from. Amounts are atomic USDC (6 decimals) decimal strings. properties: partner: type: string description: Your partner slug. as_of: $ref: '#/components/schemas/CommonTimestamp' description: When the report was read. balance: $ref: '#/components/schemas/PartnerBalance' description: What you have earned, been paid and are owed, all time. terms: type: array items: $ref: '#/components/schemas/PartnerTerms' description: Your terms, oldest first; each holds from its day until the next. from: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: First UTC day of the range. to: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: UTC day after the range. totals: $ref: '#/components/schemas/PartnerFees' description: The range's days added up. days: type: array items: $ref: '#/components/schemas/PartnerDay' description: >- Each UTC day in the range with fees, oldest first; days without fees are absent. payouts: type: array items: $ref: '#/components/schemas/PartnerPayout' description: Every payout to you, newest first. Error: properties: error: $ref: '#/components/schemas/ErrorDetail' description: The one error this request failed with. required: - error type: object CommonTimestamp: type: string format: date-time pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?Z$ maxLength: 30 PartnerBalance: type: object required: - share_bps - fees - unpriced_fees - accrued - paid - owed description: >- All time, on every vault Totalis has run in this environment. Each fee is priced at the terms in force on its UTC day. properties: share_bps: type: - integer - 'null' minimum: 0 maximum: 10000 description: >- Your current share of total fees in basis points, or null before your first terms. fees: $ref: '#/components/schemas/CommonAmount' description: Every fee charged on your positions. unpriced_fees: $ref: '#/components/schemas/CommonAmount' description: >- The part of fees charged before your first terms, which earns nothing. accrued: $ref: '#/components/schemas/CommonAmount' description: >- What you have earned: each terms period's fees times its share, rounded down. paid: $ref: '#/components/schemas/CommonAmount' description: >- What counts as paid: what landed, or a payout's whole amount while it is open or a transfer is pending. owed: type: string pattern: ^(0|-?[1-9][0-9]*)$ maxLength: 40 description: >- accrued minus paid; negative after an overpayment. Totalis decides when to pay. PartnerTerms: type: object required: - effective_from - share_bps properties: effective_from: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: First UTC day these terms price. share_bps: type: integer minimum: 0 maximum: 10000 description: Your share of total fees, in basis points. PartnerFees: allOf: - $ref: '#/components/schemas/PartnerFeeFields' unevaluatedProperties: false PartnerDay: allOf: - $ref: '#/components/schemas/PartnerFeeFields' required: - day - share_bps properties: day: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: The UTC day, by block time. share_bps: type: - integer - 'null' minimum: 0 maximum: 10000 description: The terms in force that day, or null before your first terms. unevaluatedProperties: false PartnerPayout: type: object required: - payout_id - period_start - period_end - payout_address - amount - counted - state - queued_at - closed_at - transfers properties: payout_id: type: string format: uuid description: The payout's ID. period_start: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: First day the payout is for. period_end: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: Last day the payout is for, inclusive. payout_address: $ref: '#/components/schemas/LowercaseNonZeroAddress' description: 'Where it is sent: your payout address when it was queued.' amount: $ref: '#/components/schemas/CommonAmount' description: What Totalis approved. counted: $ref: '#/components/schemas/CommonAmount' description: >- What it counts as paid: the whole amount while open or pending, then what landed. state: type: string enum: - OPEN - SETTLED - CANCELLED description: >- OPEN until its transfer is checked on-chain; SETTLED once it is; CANCELLED if dropped before anything moved. queued_at: $ref: '#/components/schemas/CommonTimestamp' description: When Totalis queued it. closed_at: anyOf: - $ref: '#/components/schemas/CommonTimestamp' - type: 'null' description: When it settled or was cancelled. transfers: type: array items: $ref: '#/components/schemas/PartnerTransfer' description: The USDC transactions sent for it on HyperEVM, oldest first. ErrorDetail: properties: code: $ref: '#/components/schemas/ErrorCode' description: Stable registered code; branch on this, not on message or status. field_violations: description: >- Each invalid input by JSON pointer; empty when the error is not about a specific input. items: $ref: '#/components/schemas/FieldViolation' type: array message: description: Human-readable; may change without notice. minLength: 1 type: string request_id: description: >- UUIDv7 of this request, also returned in the X-Request-ID header. Quote it when reporting a problem. format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string retry: $ref: '#/components/schemas/Retry' description: What the caller should do next; fixed by the registry for each code. required: - code - message - retry - request_id - field_violations type: object CommonAmount: type: string pattern: ^(0|[1-9][0-9]*)$ maxLength: 39 format: uint128-decimal PartnerFeeFields: required: - tickets - stake_volume - taker_fees - winnings_fees - buyback_fees - total_fees properties: tickets: type: integer minimum: 0 description: Positions opened through your codes. stake_volume: $ref: '#/components/schemas/CommonAmount' description: Their stake, atomic USDC. taker_fees: $ref: '#/components/schemas/CommonAmount' description: Fees charged on opening them, atomic USDC. winnings_fees: $ref: '#/components/schemas/CommonAmount' description: Fees charged on their claimed winnings, atomic USDC. buyback_fees: $ref: '#/components/schemas/CommonAmount' description: Fees charged on their cash-outs, atomic USDC. total_fees: $ref: '#/components/schemas/CommonAmount' description: 'All three together, atomic USDC: what your share is of.' LowercaseNonZeroAddress: type: string pattern: ^0x[0-9a-f]{40}$ not: const: '0x0000000000000000000000000000000000000000' PartnerTransfer: type: object required: - transaction_hash - outcome - moved - recorded_at - resolved_at properties: transaction_hash: $ref: '#/components/schemas/Bytes32' description: The HyperEVM transaction that sent it. outcome: type: string enum: - PENDING - LANDED - DEAD description: >- PENDING until checked; LANDED once its block is final; DEAD if it never landed. moved: anyOf: - $ref: '#/components/schemas/CommonAmount' - type: 'null' description: What it paid you once landed. recorded_at: $ref: '#/components/schemas/CommonTimestamp' description: When Totalis recorded the transaction. resolved_at: anyOf: - $ref: '#/components/schemas/CommonTimestamp' - type: 'null' description: When it was found landed or dead, or null while pending. ErrorCode: description: >- Stable HTTP error code. Each code has one HTTP status and one retry value. enum: - INVALID_REQUEST - INVALID_QUERY - INVALID_CURSOR - INVALID_IDEMPOTENCY_KEY - ORIGIN_REQUIRED - SUBPROTOCOL_REQUIRED - UNSUPPORTED_BROWSE_CONTRACT - UNAUTHENTICATED - FORBIDDEN - ORIGIN_NOT_ALLOWED - ACCESS_REQUIRED - NOT_FOUND - IDENTITY_NOT_FOUND - QUOTE_NOT_FOUND - INVITE_CODE_NOT_FOUND - IDEMPOTENCY_KEY_REUSED - STATE_CONFLICT - INVITE_CODE_EXHAUSTED - STALE_CURSOR - CURSOR_EXPIRED - CURSOR_RESET - RECURRING_DEFINITION_CONFLICT - EMBEDDED_WALLET_CONFLICT - SECRET_UNAVAILABLE - ROTATION_IN_PROGRESS - TELEMETRY_CONFLICT - RFQ_NOT_CANCELLABLE - RFQ_NOT_OPEN - RFQ_GENERATION_STALE - RFQ_GENERATION_IN_FLIGHT - QUOTE_EXPIRED - QUOTE_CANCELLED - QUOTE_REPLACED - QUOTE_SIGNER_CHANGED - QUOTE_CAPACITY_EXCEEDED - CORE_ACCOUNT_NOT_READY - CORE_ACCOUNT_ACTIVATION_REQUIRED - CORE_EXIT_ABANDONED - CORE_MOVE_IN_FLIGHT - USERNAME_TAKEN - USERNAME_ALREADY_SET - INVALID_SIGNATURE - WALLET_CONTRACT_UNSUPPORTED - WRONG_AUTHORITY - KEY_LIMIT_REACHED - USERNAME_NOT_ALLOWED - RATE_LIMITED - CONNECTION_LIMIT - RFQ_INTENT_LIMIT - QUOTE_EXPOSURE_LIMIT - DEPENDENCY_STALE - AUTHORIZATION_UNAVAILABLE - SOURCE_UNAVAILABLE - CONTRACT_UNAVAILABLE - MARKET_DATA_UNAVAILABLE - BROWSE_UNAVAILABLE - FINANCIAL_ACTIONS_DISABLED - CORE_EXIT_UNAVAILABLE - COLLATERAL_REDUCTION_UNAVAILABLE - SPONSORSHIP_UNAVAILABLE - CONTRACT_SIGNATURE_OVERLOADED - QUOTE_EXPOSURE_STALE - COMBO_AUTOMATIC_DISABLED - GAS_PRICE_ABOVE_CEILING - EMBEDDED_WALLET_UNAVAILABLE - CONNECTION_DRAIN type: string FieldViolation: properties: code: description: >- REQUIRED: the input is missing. INVALID: it is present but malformed or out of range. UNEXPECTED: the input is not accepted here. enum: - REQUIRED - INVALID - UNEXPECTED type: string field: description: >- JSON pointer into the body, or into the query parameters as one flat object for requests without a body, for example /legs/0/stake or /limit. pattern: ^(/([^~/]|~[01])*)+$ type: string required: - field - code type: object Retry: description: >- NEVER: stop. BACKOFF: resend the same request with the same Idempotency-Key after Retry-After. REFRESH: re-read state, then send a new request with a new Idempotency-Key. enum: - NEVER - BACKOFF - REFRESH type: string Bytes32: type: string pattern: ^0x[0-9a-f]{64}$ headers: RetryAfter: description: Seconds to wait before resending the same request schema: type: integer minimum: 1 securitySchemes: partnerServerKey: type: http scheme: bearer bearerFormat: tpk_ description: >- Partner server key (`tpk_...`), issued by Totalis to a registered partner. It calls only `POST /v1/partner/wallet-admissions` and `GET /v1/partner/report`, from the partner's server with no `Origin`; it cannot act for an account. Never ship it to a browser: pages use the publishable browser key (`X-Totalis-Partner: tpb_...`), which labels traffic but authorizes nothing. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.