> ## 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. # Create withdrawal > Withdraw USDC from your Totalis balance to an external address. Requires a key for your account with `funding:withdraw`, `sponsorship:use`. ## OpenAPI ````yaml /hyperliquid/openapi.json post /v1/me/withdrawals 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. Authenticate with a scoped API key created in the Totalis app, sent as `Authorization: Bearer `. Public market reads need no key. Balance-affecting commands also carry the wallet or maker signature the HyperEVM contract verifies. 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: 127.0.0-pure-reads 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 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 and withdrawals. - name: Makers description: 'The rest of a maker''s setup after Making: capital and collateral.' - name: Deployment description: The contract deployment every signature is made against. - name: WebSocket description: The authenticated WebSocket for account and maker updates. paths: /v1/me/withdrawals: post: tags: - Account summary: Create withdrawal description: >- Withdraw USDC from your Totalis balance to an external address. Requires a key for your account with `funding:withdraw`, `sponsorship:use`. operationId: createWithdrawal parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WithdrawalCommand' example: destination: '0x2222222222222222222222222222222222222222' amount: '15000000' vault_withdrawal: amount: '10000000' expiry: '1790434800' salt: '4919131752989213764' signature: >- 0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef payout_authorization: valid_after: '1790433540' valid_before: '1790435100' authorization_signature: >- 0x9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e9e1b responses: '202': description: >- Admitted, not yet paid: Totalis tops your wallet up from the vault if needed, relays the payout and pays the gas. Follow `WITHDRAWAL_UPDATED` on the account stream until `PAYOUT_COMMITTED` or `FAILED`. A retry with the same `Idempotency-Key` and body returns the withdrawal as it stands. content: application/json: schema: $ref: '#/components/schemas/Withdrawal' example: withdrawal_id: 01998683-7a31-7e5a-a3c1-6f2b8d4e9a17 account: '0x1111111111111111111111111111111111111111' destination: '0x2222222222222222222222222222222222222222' amount: '15000000' shortfall_amount: '10000000' status: VAULT_WITHDRAWAL_QUEUED vault_operation_id: >- 0x3a7d1e9c5b2f8a4e6d1c9b3f7a5e2d8c4b1f6a9e3d7c2b5f8a1e4d9c6b3f7a20 payout_operation_id: null payout_transaction_hash: null updated_at: '2026-09-26T14:30:00.412000Z' '400': description: >- - `INVALID_REQUEST` (retry `NEVER`): The body, a path parameter or a header is malformed or fails validation. `field_violations` names invalid body fields. - `INVALID_IDEMPOTENCY_KEY` (retry `NEVER`): The command needs exactly one lowercase UUIDv7 `Idempotency-Key` header; confirm takes none. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' '401': description: >- - `UNAUTHENTICATED` (retry `NEVER`): The credential is missing, invalid, expired or revoked. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' '403': description: >- - `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' '409': description: >- - `IDEMPOTENCY_KEY_REUSED` (retry `NEVER`): The idempotency key was already used with different input. - `STATE_CONFLICT` (retry `REFRESH`): The resource changed and no longer admits this request. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' '422': description: >- - `INVALID_SIGNATURE` (retry `NEVER`): The signature does not verify for the signed terms. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' '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' '503': description: >- - `AUTHORIZATION_UNAVAILABLE` (retry `BACKOFF`): Identity or credential authority storage is unavailable. - `DEPENDENCY_STALE` (retry `BACKOFF`): A projection or upstream the request depends on (chain projection, HyperCore state, database) is behind its freshness bound or unavailable. - `FINANCIAL_ACTIONS_DISABLED` (retry `BACKOFF`): Financial actions are disabled for this deployment. - `CONTRACT_SIGNATURE_OVERLOADED` (retry `BACKOFF`): Contract signature verification is at capacity. - `SPONSORSHIP_UNAVAILABLE` (retry `BACKOFF`): Venue gas sponsorship is unavailable. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' security: - apiKey: - funding:withdraw - sponsorship:use components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string 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}$ description: >- Lowercase UUIDv7 naming this command, unique per caller and route. A retry with the same key and body returns the original result; the same key with a different body returns `409 IDEMPOTENCY_KEY_REUSED`. example: 0198a6f6-82a5-7abc-9f2a-4f0fb437493e schemas: WithdrawalCommand: description: >- The whole withdrawal in one request: pay amount from the embedded wallet to destination, topping the wallet up from the vault first when it cannot cover the amount. The owner signs the vault Exit for the shortfall and the USDC payout together; Totalis relays both, in order, and pays the gas. type: object additionalProperties: false required: - destination - amount - payout_authorization properties: destination: $ref: '#/components/schemas/LowercaseNonZeroAddress' description: External address that receives the USDC. amount: $ref: '#/components/schemas/CommonAmount' description: >- Total amount to send, in atomic USDC (6 decimals); must be greater than zero. vault_withdrawal: $ref: '#/components/schemas/VaultWithdrawal' description: >- Signed Exit moving the exact shortfall (amount minus spendable wallet USDC) from the vault back to the embedded wallet. Required when there is a shortfall and forbidden when there is none; a mismatch returns 409 STATE_CONFLICT with retry REFRESH: re-read balances and sign again. payout_authorization: description: >- The embedded wallet's USDC EIP-3009 TransferWithAuthorization of exactly amount to destination. Its nonce is not sent: sign keccak256(abi.encode(keccak256("TOTALIS_PAYOUT_NONCE_V1"), chainId, vault, account, uint128(Idempotency-Key))), where account is the embedded wallet and Idempotency-Key is this request's key read as 16 bytes. The signature is therefore bound to this request and cannot start a second withdrawal. Choose the `Idempotency-Key` before you sign. type: object additionalProperties: false required: - valid_after - valid_before - authorization_signature properties: valid_after: $ref: '#/components/schemas/UInt64String' description: EIP-3009 validAfter in Unix seconds; must not be in the future. valid_before: $ref: '#/components/schemas/UInt64String' description: >- EIP-3009 validBefore in Unix seconds: at least 300 seconds after vault_withdrawal.expiry (or after now when there is no shortfall), so the payout can still be relayed once the vault leg lands, and at most 4500 seconds after valid_after. authorization_signature: $ref: '#/components/schemas/Signature65' description: >- 65-byte ECDSA signature by the embedded wallet over the USDC TransferWithAuthorization(from=wallet, to=destination, value=amount, validAfter, validBefore, nonce) message. Withdrawal: type: object additionalProperties: false required: - withdrawal_id - account - destination - amount - shortfall_amount - status - vault_operation_id - payout_operation_id - payout_transaction_hash - updated_at properties: withdrawal_id: $ref: '#/components/schemas/Uuid' description: Server-assigned ID of this withdrawal. account: $ref: '#/components/schemas/LowercaseNonZeroAddress' description: Embedded wallet that pays out. destination: $ref: '#/components/schemas/LowercaseNonZeroAddress' description: External address that receives the USDC. amount: $ref: '#/components/schemas/CommonAmount' description: Total amount sent to destination, in atomic USDC (6 decimals). shortfall_amount: $ref: '#/components/schemas/CommonAmount' description: >- Part of amount first withdrawn from the vault to the wallet, in atomic USDC; "0" when the wallet already covered it. status: description: >- VAULT_WITHDRAWAL_QUEUED: the vault top-up is queued and the payout waits for it; PAYOUT_SUBMITTED: the payout is queued or relayed; PAYOUT_COMMITTED: destination received amount (terminal); FAILED: the withdrawal stopped and nothing left the Totalis balance: a vault top-up that committed stays in the wallet (terminal). enum: - VAULT_WITHDRAWAL_QUEUED - PAYOUT_SUBMITTED - PAYOUT_COMMITTED - FAILED vault_operation_id: description: Operation of the vault top-up; null when there is no shortfall. oneOf: - $ref: '#/components/schemas/Bytes32' - type: 'null' payout_operation_id: description: >- Operation of the relayed payout; null until the vault top-up commits. oneOf: - $ref: '#/components/schemas/Bytes32' - type: 'null' payout_transaction_hash: description: HyperEVM transaction of the payout; null until it is broadcast. oneOf: - $ref: '#/components/schemas/Bytes32' - type: 'null' updated_at: $ref: '#/components/schemas/CommonTimestamp' description: When the withdrawal last changed, RFC3339 UTC. Error: additionalProperties: false properties: error: $ref: '#/components/schemas/ErrorDetail' description: The one error this request failed with. required: - error type: object LowercaseNonZeroAddress: type: string pattern: ^0x[0-9a-f]{40}$ description: Never `0x0000000000000000000000000000000000000000`. CommonAmount: type: string pattern: ^(0|[1-9][0-9]*)$ maxLength: 39 format: uint128-decimal VaultWithdrawal: description: >- Owner-signed EIP-712 Exit that moves the withdrawal's shortfall from the vault to the embedded wallet; Totalis relays it and pays gas. The signed Exit's account and to are both the caller's embedded wallet, which the venue fills in. type: object additionalProperties: false required: - amount - expiry - salt - signature properties: amount: $ref: '#/components/schemas/CommonAmount' description: >- Shortfall in atomic USDC (6 decimals): the withdrawal amount minus spendable wallet USDC; must be greater than zero. expiry: $ref: '#/components/schemas/UInt64String' description: >- Exit expiry in Unix seconds; must be at least 5 seconds ahead and at most 3600 seconds ahead, less a 5-second clock-skew margin. salt: $ref: '#/components/schemas/Uint' description: >- Caller-chosen uint256 as a decimal string that makes the signed Exit unique. signature: $ref: '#/components/schemas/ContractSignature' description: >- Signature by the embedded wallet over the EIP-712 Exit(account,to,amount,expiry,salt) digest, with account and to the wallet; ECDSA or ERC-1271 contract signature bytes. UInt64String: type: string pattern: >- ^(0|[1-9][0-9]{0,18}|1[0-7][0-9]{18}|18[0-3][0-9]{17}|184[0-3][0-9]{16}|1844[0-5][0-9]{15}|18446[0-6][0-9]{14}|184467[0-3][0-9]{13}|1844674[0-3][0-9]{12}|184467440[0-6][0-9]{10}|1844674407[0-2][0-9]{9}|18446744073[0-6][0-9]{8}|1844674407370[0-8][0-9]{6}|18446744073709[0-4][0-9]{5}|184467440737095[0-4][0-9]{4}|18446744073709550[0-9]{3}|18446744073709551[0-5][0-9]{2}|1844674407370955160[0-9]|1844674407370955161[0-5])$ maxLength: 20 format: uint64-decimal Signature65: type: string pattern: ^0x[0-9a-f]{130}$ Uuid: type: string 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}$ Bytes32: type: string pattern: ^0x[0-9a-f]{64}$ 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 ErrorDetail: additionalProperties: false 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 Uint: type: string pattern: ^(0|[1-9][0-9]*)$ maxLength: 78 format: uint256-decimal ContractSignature: type: string pattern: ^0x(?:[0-9a-f]{2}){1,4096}$ 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_EXIT_ABANDONED - CORE_FUNDING_CONFLICT - CORE_VAULT_RESERVATION - CORE_MOVE_IN_FLIGHT - INVALID_SIGNATURE - WRONG_AUTHORITY - KEY_LIMIT_REACHED - HYPERCORE_WALLET_UNQUALIFIED - HYPERCORE_ACCOUNT_NOT_MAIN - HYPERCORE_INSUFFICIENT_BALANCE - 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_FUNDING_UNAVAILABLE - CORE_EXIT_UNAVAILABLE - SPONSORSHIP_UNAVAILABLE - CONTRACT_SIGNATURE_OVERLOADED - QUOTE_EXPOSURE_STALE - COMBO_AUTOMATIC_DISABLED - EMBEDDED_WALLET_UNAVAILABLE - CONNECTION_DRAIN type: string FieldViolation: additionalProperties: false 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 headers: RetryAfter: description: Seconds to wait before resending the same request schema: type: integer minimum: 1 securitySchemes: apiKey: type: http scheme: bearer description: >- Scoped API key from the Totalis app settings. Each key acts for one account, yours or a maker's, and holds only scopes that account can use. Each operation lists the scopes it requires. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.