> ## 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 collateral reduction > Get a collateral-reduction job. Requires a key for a maker with `vault:read` and the maker permission `READ_CAPITAL`. ## OpenAPI ````yaml /hyperliquid/openapi.json get /v1/makers/{maker_id}/collateral-reductions/{job_id} 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/makers/{maker_id}/collateral-reductions/{job_id}: parameters: - $ref: '#/components/parameters/MakerId' - $ref: '#/components/parameters/CollateralReductionJobId' get: tags: - Makers summary: Get collateral reduction description: >- Get a collateral-reduction job. Requires a key for a maker with `vault:read` and the maker permission `READ_CAPITAL`. operationId: getCollateralReduction responses: '200': description: >- The job, with its own status reported separately from the on-chain operation that applies it and that operation's chain evidence. content: application/json: schema: $ref: '#/components/schemas/CollateralReduction' example: job_id: 01998713-2f4a-7c3e-9b1d-6a0e4f5c8d21 maker_id: '7' status: DURABLE snapshot_block: '31842090' catalog_generation: '6110' gross0: '412500000000' risk0: '187250000000' turnover0: '96400000000' nonce: '3' expiry: '1790431620' digest: >- 0xe5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5 operation_id: >- 0xf6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6f6 operation_status: QUEUED transaction: chain_id: '999' to: '0xedf7131c57e0ac4eade509e1bf56a9ab7af43745' data: >- 0x22879f2b0000000000000000000000000000000000000000000000000000000000000007000000000000000000000000000000000000000000000000000000600aea7d000000000000000000000000000000000000000000000000000000002b98f840800000000000000000000000000000000000000000000000000000001671e344000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000006ab7d058000000000000000000000000000000000000000000000000000000006ab7d184000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000415e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e00000000000000000000000000000000000000000000000000000000000000 value: '0' failure_code: null next_eligible_at: '2026-09-26T14:07:00Z' created_at: '2026-09-26T14:02:00.214Z' updated_at: '2026-09-26T14:02:03.870Z' '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. 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' '404': description: >- - `NOT_FOUND` (retry `NEVER`): The resource does not exist or is not visible to this credential. 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. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' security: - apiKey: - vault:read components: parameters: MakerId: name: maker_id in: path required: true schema: $ref: '#/components/schemas/NonZeroUInt64String' description: >- On-chain maker ID, as a decimal string. The credential must be authorized for this maker. example: '3' CollateralReductionJobId: name: job_id in: path required: true schema: $ref: '#/components/schemas/Uuid' description: Collateral-reduction job ID returned when the job was created. example: 01994f3b-1a2b-7c3d-8e4f-5a6b7c8d9e0f schemas: CollateralReduction: type: object additionalProperties: false required: - job_id - maker_id - status - snapshot_block - catalog_generation - gross0 - risk0 - turnover0 - nonce - expiry - digest - operation_id - operation_status - transaction - failure_code - next_eligible_at - created_at - updated_at properties: job_id: $ref: '#/components/schemas/Uuid' description: ID of the collateral-reduction job. maker_id: $ref: '#/components/schemas/NonZeroUInt64String' description: Maker whose collateral requirement the job reduces. status: description: >- QUEUED: waiting until the maker is eligible for a reduction; SOLVING: computing the requirement; NO_IMPROVEMENT: no lower requirement found, nothing to submit; DURABLE: certificate signed and ATTEST operation stored; FAILED: ended without a certificate. enum: - QUEUED - SOLVING - NO_IMPROVEMENT - DURABLE - FAILED snapshot_block: description: >- HyperEVM block of the maker's open-book snapshot; null until the snapshot is taken. oneOf: - $ref: '#/components/schemas/UInt64String' - type: 'null' catalog_generation: description: >- Market-catalog generation the snapshot is bound to; null until the snapshot is taken. oneOf: - $ref: '#/components/schemas/UInt64String' - type: 'null' gross0: description: >- Gross collateral requirement of the snapshot book in atomic USDC (6 decimals); null until the snapshot is taken. oneOf: - $ref: '#/components/schemas/CommonAmount' - type: 'null' risk0: description: >- Proven worst-case requirement of the snapshot book in atomic USDC (6 decimals); null until solved. oneOf: - $ref: '#/components/schemas/CommonAmount' - type: 'null' turnover0: description: >- Maker's settled turnover at the snapshot in atomic USDC (6 decimals), as signed into the certificate; null until the snapshot is taken. oneOf: - $ref: '#/components/schemas/CommonAmount' - type: 'null' nonce: description: >- Attestor nonce signed into the certificate; null without a certificate. oneOf: - $ref: '#/components/schemas/Uint' - type: 'null' expiry: description: >- Certificate expiry in Unix seconds, two minutes after signing; null without a certificate. oneOf: - $ref: '#/components/schemas/UInt64String' - type: 'null' digest: description: >- EIP-712 Attestation digest the attestor signed; null without a certificate. oneOf: - $ref: '#/components/schemas/Bytes32' - type: 'null' operation_id: description: >- Maker-owned ATTEST operation that carries the certificate on chain; null without a certificate. oneOf: - $ref: '#/components/schemas/Bytes32' - type: 'null' operation_status: description: Current status of the ATTEST operation; null without one. oneOf: - $ref: '#/components/schemas/OperationState' - type: 'null' transaction: description: >- Exact zero-value call for the maker to sign with its own gas account and submit through the self-funded transaction endpoint; null unless the operation is DURABLE and the certificate unexpired. oneOf: - $ref: '#/components/schemas/TransactionCall' - type: 'null' failure_code: description: >- Machine-readable reason the job failed, e.g. COOLDOWN_CHANGED; null otherwise. type: - string - 'null' maxLength: 64 next_eligible_at: $ref: '#/components/schemas/CommonTimestamp' description: >- Earliest RFC 3339 UTC time the maker's next reduction can land on chain; the job stays QUEUED until then. created_at: $ref: '#/components/schemas/CommonTimestamp' description: RFC 3339 UTC time the job was created. updated_at: $ref: '#/components/schemas/CommonTimestamp' description: RFC 3339 UTC time the job last changed. Error: additionalProperties: false properties: error: $ref: '#/components/schemas/ErrorDetail' description: The one error this request failed with. required: - error type: object NonZeroUInt64String: allOf: - $ref: '#/components/schemas/UInt64String' description: Never `0`. 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}$ 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 CommonAmount: type: string pattern: ^(0|[1-9][0-9]*)$ maxLength: 39 format: uint128-decimal Uint: type: string pattern: ^(0|[1-9][0-9]*)$ maxLength: 78 format: uint256-decimal Bytes32: type: string pattern: ^0x[0-9a-f]{64}$ OperationState: enum: - QUEUED - IN_FLIGHT - RETRYABLE - UNKNOWN - COMMITTED - REVERTED - EXPIRED_UNEXECUTED TransactionCall: type: object additionalProperties: false required: - chain_id - to - data - value properties: chain_id: enum: - '998' - '999' description: 'HyperEVM chain ID for the transaction: 998 testnet or 999 mainnet.' to: $ref: '#/components/schemas/LowercaseNonZeroAddress' description: Vault contract address to call. data: type: string pattern: ^0x[0-9a-f]+$ description: Canonical ABI-encoded calldata built by the server; lowercase hex. value: const: '0' description: Native value in wei; always zero. 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 LowercaseNonZeroAddress: type: string pattern: ^0x[0-9a-f]{40}$ description: Never `0x0000000000000000000000000000000000000000`. 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.