Create

Initiates a withdrawal to the specified destination address. The payout enters queued status and executes asynchronously.

Idempotency: Idempotency-Key is required, and exact request replays are idempotent — they return the original payout without moving funds twice.

The conflict check covers the complete request: path parameters, query and the canonical body. Reusing a key with a different value for ANY field, annotations such as description and metadata included, returns 409 with code conflict. Retry the original request — see Idempotency-Key.

Native gate amounts stay separate from the payout amount, and an accepted funding intent is immutable: a merchant with an active funding grant may pass funding to override its policy within that grant.

Usage notes#

Initiates a withdrawal to the specified destination address. The payout enters queued status and executes asynchronously.

Idempotency-Key is required, and an exact request replay is idempotent: it returns the original payout without moving funds twice. The conflict check covers the complete request, annotations such as description and metadata included; reusing a key with a different value for any field returns 409 conflict. Retry the original request — see idempotency.

Requires payouts:write. Use a recipient-confirmed destination and destination_tag where required. Example addresses are placeholders; do not send real funds to them.

A successful response accepts the payout for execution and reserves what funds it. amount is the requested principal, recipient_amount is sent to the recipient, target_funding_amount is the target-denominated obligation, and balance_movements carries the effect on every participating currency and network. There is no scalar merchant debit. Actual network_fee is separate from the commercial network charge and is never added to the target obligation.

Omit funding to use the saved merchant policy. An explicit source override must stay within the current grant. Preserve the original body and idempotency key after an unknown outcome. See funding semantics.

There is no external_id field; use metadata, which is returned on the payout. Save your local withdrawal mapping and payout ID before relying on notifications. See payout lifecycle and amounts.

POST/v1/payouts

curl --request POST 'https://api.thehalfin.com/v1/payouts' \
  --header "X-API-Key: $HALFIN_API_KEY" \
  --header 'Idempotency-Key: createPayout-example-1001' \
  --header 'Content-Type: application/json' \
  --data '{
  "currency": "USDC",
  "network": "ethereum",
  "amount": "10.00",
  "destination": "0x0000000000000000000000000000000000000001",
  "beneficiary_type": "third_party",
  "description": "Withdrawal 1001",
  "metadata": {
    "withdrawal_id": "1001"
  }
}'

Authorization

X-API-KeystringRequired
API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.
Example: $HALFIN_API_KEY

Header Parameters

Idempotency-KeystringRequired
Persist a unique key before sending this operation. Retry an uncertain outcome with the same key and unchanged request; a new operation needs a new key.
See idempotency and retries for replay, conflict, and key-release behavior.
Full header contract
Required for merchant POST requests that create invoices, addresses, payouts, or refunds. Use a unique key for each intended operation. The same key namespace is shared by all merchant operations within the same merchant and environment. Retry the original request with the same key and unchanged path, query, and body. JSON key ordering and insignificant whitespace are ignored; numeric literals and string values are preserved ("10" differs from "10.00"). Changing any field under a bound key returns 409 conflict. An executing request returns 409 in_flight. An exact retry returns the permanent original outcome with Idempotent-Replayed: true. Only Idempotency-Key-Released: true confirms that a refused attempt released the key. An unconfirmed release returns 503 service_unavailable without that header. Under uncertainty, retry the original request with the same key. The key is never echoed in response bodies. Keys contain 1–255 printable ASCII characters without spaces; a UUID is recommended.
- Minimum length: 1
- Maximum length: 255
- Pattern: ^[\x21-\x7E]+$
Example: createPayout-example-1001

Request Body

Required

application/json

currencystringRequired
Cryptocurrency code.
- Minimum length: 1
- Maximum length: 20
Example: string
networkstringRequired
Blockchain network of the payout asset (e.g. ethereum, solana, tron). Required together with currency; an unknown pair returns 422 gate_unknown.
- Minimum length: 1
- Maximum length: 64
Example: string
amountstringRequired
Decimal string amount to send.
- Maximum length: 50
Example: 1
destinationstringRequired
Destination blockchain address. The owning rail decides whether the address is usable on this network; an address the rail refuses is answered `422` with code `unprocessable_entity`, not `400` — the string is well formed and the network is what rejects it.
- Maximum length: 256
Example: string
destination_tagstringOptional
Memo/tag for chains that require it.
- Maximum length: 256
Example: string
beneficiary_type"self" | "third_party"Required
Who receives the funds, declared by the merchant on every payout. `self` — the merchant's own wallet or its own account at an exchange; `third_party` — a wallet that belongs to someone else (a customer, a partner, a payroll recipient). Required on creation, no default. The platform stores the declared value and returns it on the payout; it does not change how the payout executes. Travel Rule handling branches on this axis, so the declaration must be truthful.
Example: self
descriptionstringOptional
Human-readable payout description.
- Maximum length: 1000
Example: string
metadataobjectOptional
Merchant key-value metadata; omitted invoice metadata is stored and returned as an empty object.
- Maximum properties: 50
Example: {"key":"string"}
- [key]stringOptional
  - Maximum length: 500
  Example: string
fundingobjectOptional
Optional request override within the current merchant grant. Omitted uses the current merchant policy; accepted requests freeze their funding intent.
- Unknown properties are rejected
Example: {"mode":"same_asset_only","source":null,"service_class":"immediate","max_wait_seconds":0}
- mode"same_asset_only" | "source_only" | "target_first"Required
  Example: same_asset_only
- sourceobject | nullRequired
  - Unknown properties are rejected
  Example: null
  - currencystringRequired
    - Minimum length: 1
    - Maximum length: 20
    Example: string
  - networkstringRequired
    - Minimum length: 1
    - Maximum length: 64
    Example: string
- service_class"immediate" | "waiting"Required
  Example: immediate
- max_wait_secondsintegerRequired
  - Minimum: 0
  - Maximum: 2147483647
  Example: 0

Response Body

201 The payout.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

dataobjectRequired
- Unknown properties are rejected
Example: {"id":"00000000-0000-0000-0000-000000000003","currency":"USDC","network":"ethereum","amount":"10.00","recipient_amount":"10.00","amount_in_base_currency":null,"network_fee":null,"network_fee_currency":null,"network_fee_network":null,"fee_amount":"0.10","payout_fee_allocation":"merchant","configured_network_fee_amount":"0.00","network_fee_allocation":"platform","destination":"0x0000000000000000000000000000000000000001","destination_tag":null,"beneficiary_type":"third_party","status":"queued","environment":"live","tx_hash":null,"description":"Withdrawal 1001","executable_at":null,"completed_at":null,"created_at":"2026-09-14T10:00:00Z","updated_at":"2026-09-14T10:00:00Z","failure_reason":null,"operation_id":null,"target_funding_amount":"10.10","funding":null,"balance_movements":[],"economics_status":"available","metadata":{"withdrawal_id":"1001"},"created_by_id":null}
- idstringRequired
  Payout UUID.
  - Format: uuid
  Example: 00000000-0000-0000-0000-000000000001
- currencystringRequired
  Cryptocurrency code.
  Example: string
- networkstringRequired
  Blockchain network key for explorer and gate routing.
  Example: string
- amountstringRequired
  Base/requested payout amount. This field keeps its historical meaning.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: 1
- recipient_amountstring | nullRequired
  Amount sent to the recipient after customer-allocated commercial charges.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- amount_in_base_currencystring | nullRequired
  Historical USD display valuation from the accepted pricing snapshot. Null when that snapshot has no valuation; current rates are never substituted.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- network_feestring | nullRequired
  Actual processor-reported on-chain network cost denominated in `network_fee_currency` on `network_fee_network`. Null until the payout reaches a terminal state and the processor reports that cost: before completion the actual cost does not exist, and the configured estimate is never substituted for it. The snapshotted commercial charge is the separate `configured_network_fee_amount` field, which is populated from creation in payout currency. The actual on-chain cost is not added to `target_funding_amount`.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- network_fee_currencystring | nullRequired
  Currency of the actual processor-reported network fee.
  Example: null
- network_fee_networkstring | nullRequired
  Network of the actual processor-reported network fee.
  Example: null
- fee_amountstring | nullRequired
  Decimal string of the platform payout fee in payout currency.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- payout_fee_allocation"customer" | "merchant" | "platform" | nullRequired
  Allocation of the snapshotted payout service fee.
  Example: null
- configured_network_fee_amountstring | nullRequired
  Snapshotted commercial network charge in payout currency; distinct from actual on-chain cost.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- network_fee_allocation"customer" | "merchant" | "platform" | nullRequired
  Allocation of the commercial `configured_network_fee_amount` in payout currency, not the actual on-chain `network_fee`.
  Example: null
- destinationstringRequired
  Destination blockchain address.
  Example: string
- destination_tagstring | nullRequired
  Memo/tag if applicable.
  Example: null
- beneficiary_type"self" | "third_party"Required
  Who receives the funds, declared by the merchant on every payout. `self` — the merchant's own wallet or its own account at an exchange; `third_party` — a wallet that belongs to someone else (a customer, a partner, a payroll recipient). Required on creation, no default. The platform stores the declared value and returns it on the payout; it does not change how the payout executes. Travel Rule handling branches on this axis, so the declaration must be truthful.
  Example: self
- status"queued" | "processing" | "confirming" | "completed" | "failed" | "cancelled" | "reversed"Required
  Payout status. `processing` covers the whole span between dispatch and a terminal outcome: the merchant's funds stay reserved until the payout reaches `completed` or `failed`. `cancelled` is retained in this enum for compatibility but is not emitted for an individual payout.
  Example: queued
- environment"live" | "test"Required
  Environment this payout belongs to.
  Example: live
- tx_hashstring | nullRequired
  On-chain transaction hash (populated after broadcast).
  Example: null
- descriptionstringRequired
  Payout description.
  Example: string
- executable_atstring | nullRequired
  Earliest time the payout can be executed.
  - Format: date-time
  Example: null
- completed_atstring | nullRequired
  Completion timestamp.
  - Format: date-time
  Example: null
- created_atstringRequired
  Creation timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- updated_atstringRequired
  Last update timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- failure_reasonstring | nullRequired
  Merchant-facing terminal reason. A failed payout reports destination_rejected for a rejected destination, or internal_error for other failures. A reversed payout reports reorg. Null while queued, processing, confirming, or completed.
  Example: null
- operation_idstring | nullRequired
  Finance operation UUID linked to this payout.
  - Format: uuid
  Example: null
- target_funding_amountstring | nullRequired
  Target-denominated obligation H. It is not a source-gate debit.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: null
- fundingobject | nullRequired
  Frozen multi-source funding and its durable progress. Null for ordinary source-free payouts and historical payouts without accepted economics.
  - Unknown properties are rejected
  Example: null
  - mode"same_asset_only" | "source_only" | "target_first"Required
    Example: same_asset_only
  - service_class"immediate" | "waiting"Required
    Example: immediate
  - direct_target_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - target_ready_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - target_surplus_releasedstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - funding_deadlinestring | nullRequired
    - Format: date-time
    Example: null
  - sourcesarray<object>Required
    Example: [{"conversion_fee_payer":"merchant","source_id":"00000000-0000-0000-0000-000000000001","gate":{"currency":"string","network":"string"},"reserved_gross":"1","exchanged_principal":"1","earned_conversion_fee":"1","refunded_source":"1","outstanding_reserve":"1","target_delivered":"1"}]
    - conversion_fee_payer"merchant" | "platform"Required
      Example: merchant
    - source_idstringRequired
      - Format: uuid
      Example: 00000000-0000-0000-0000-000000000001
    - gateobjectRequired
      - Unknown properties are rejected
      Example: {"currency":"string","network":"string"}
      - currencystringRequired
        Minimum length: 1
        Maximum length: 20
        Example: string
      - networkstringRequired
        Minimum length: 1
        Maximum length: 64
        Example: string
    - reserved_grossstringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - exchanged_principalstringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - earned_conversion_feestringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - refunded_sourcestringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - outstanding_reservestringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
    - target_deliveredstringRequired
      - Format: decimal
      - Pattern: ^\d+(\.\d+)?$
      Example: 1
  - status"converting" | "needs_review" | "ready" | "closed"Required
    Funding lifecycle within the payout. The outer payout status remains processing during converting and needs_review.
    Example: converting
- balance_movementsarray<object>Required
  Example: [{"gate":{"currency":"string","network":"string"},"direction":"credit","amount":"1","credit_amount":"1","debit_amount":"1","reversed_credit_amount":"1","reversed_debit_amount":"1","amount_usd":null}]
  - gateobjectRequired
    - Unknown properties are rejected
    Example: {"currency":"string","network":"string"}
    - currencystringRequired
      - Minimum length: 1
      - Maximum length: 20
      Example: string
    - networkstringRequired
      - Minimum length: 1
      - Maximum length: 64
      Example: string
  - direction"credit" | "debit" | "none"Required
    Example: credit
  - amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - credit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - debit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - reversed_credit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - reversed_debit_amountstringRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: 1
  - amount_usdstring | nullRequired
    - Format: decimal
    - Pattern: ^\d+(\.\d+)?$
    Example: null
- economics_status"available" | "unavailable"Required
  Available when the original accepted commercial snapshot exists. Unavailable historical economics are null; current prices never reconstruct them.
  Example: available
- metadataobjectRequired
  Merchant key-value metadata; omitted invoice metadata is stored and returned as an empty object.
  - Maximum properties: 50
  Example: {"key":"string"}
  - [key]stringOptional
    - Maximum length: 500
    Example: string
- created_by_idstring | nullRequired
  Dashboard user who created this payout. `null` when it was created through the API or expanded from a batch, which is what tells the two apart.
  - Format: uuid
  Example: null
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000003",
    "currency": "USDC",
    "network": "ethereum",
    "amount": "10.00",
    "recipient_amount": "10.00",
    "amount_in_base_currency": null,
    "network_fee": null,
    "network_fee_currency": null,
    "network_fee_network": null,
    "fee_amount": "0.10",
    "payout_fee_allocation": "merchant",
    "configured_network_fee_amount": "0.00",
    "network_fee_allocation": "platform",
    "destination": "0x0000000000000000000000000000000000000001",
    "destination_tag": null,
    "beneficiary_type": "third_party",
    "status": "queued",
    "environment": "live",
    "tx_hash": null,
    "description": "Withdrawal 1001",
    "executable_at": null,
    "completed_at": null,
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:00:00Z",
    "failure_reason": null,
    "operation_id": null,
    "target_funding_amount": "10.10",
    "funding": null,
    "balance_movements": [],
    "economics_status": "available",
    "metadata": {
      "withdrawal_id": "1001"
    },
    "created_by_id": null
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

400 `validation_error`: Validation error.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"validation_error","message":"string","details":["string"]}
- code"validation_error"Required
  `validation_error`: Validation error.
  Example: validation_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

401 `unauthorized`: Unauthorized.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unauthorized","message":"string","details":["string"]}
- code"unauthorized"Required
  `unauthorized`: Unauthorized.
  Example: unauthorized
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

403 `forbidden`: Forbidden. `api_key_ip_forbidden`: Api key ip forbidden.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"forbidden","message":"string","details":["string"]}
- code"forbidden" | "api_key_ip_forbidden"Required
  `forbidden`: Forbidden. `api_key_ip_forbidden`: Api key ip forbidden.
  Example: forbidden
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "forbidden",
    "message": "Permission denied"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

404 `not_found`: Not found.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"not_found","message":"string","details":["string"]}
- code"not_found"Required
  `not_found`: Not found.
  Example: not_found
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

409 `conflict`: Conflict. `in_flight`: In flight. `funding_policy_conflict`: The funding policy changed before acceptance. `funding_grant_conflict`: The funding grant changed before acceptance.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"conflict","message":"string","details":["string"]}
- code"conflict" | "in_flight" | "funding_policy_conflict" | "funding_grant_conflict"Required
  `conflict`: Conflict. `in_flight`: In flight. `funding_policy_conflict`: The funding policy changed before acceptance. `funding_grant_conflict`: The funding grant changed before acceptance.
  Example: conflict
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "conflict",
    "message": "Request conflicts with the existing state"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

422 `unprocessable_entity`: Unprocessable entity. `gate_unknown`: Gate unknown. `funding_not_granted`: The selected funding preferences are outside the grant. `funding_allocation_limit`: Funding the payout would exceed the grant's per-source allocation lineage bound or the derived payout-wide bound. `funding_conversion_fee_payer_invalid`: Funding conversion fee payer must be merchant or platform. `funding_balance_insufficient`: Eligible native balances cannot fund the payout. `funding_route_unavailable`: No eligible route with required platform or physical liquidity can fund the payout.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unprocessable_entity","message":"string","details":["string"]}
- code"unprocessable_entity" | "gate_unknown" | "funding_not_granted" | "funding_allocation_limit" | "funding_conversion_fee_payer_invalid" | "funding_balance_insufficient" | "funding_route_unavailable"Required
  `unprocessable_entity`: Unprocessable entity. `gate_unknown`: Gate unknown. `funding_not_granted`: The selected funding preferences are outside the grant. `funding_allocation_limit`: Funding the payout would exceed the grant's per-source allocation lineage bound or the derived payout-wide bound. `funding_conversion_fee_payer_invalid`: Funding conversion fee payer must be merchant or platform. `funding_balance_insufficient`: Eligible native balances cannot fund the payout. `funding_route_unavailable`: No eligible route with required platform or physical liquidity can fund the payout.
  Example: unprocessable_entity
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "unprocessable_entity",
    "message": "The request cannot be processed in the current state"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

500 `internal_error`: Internal error.

Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true
Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"internal_error","message":"string","details":["string"]}
- code"internal_error"Required
  `internal_error`: Internal error.
  Example: internal_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

503 `service_unavailable`: Service unavailable.

Idempotency-Key-Released"true"Optional
Present and true after a proven no-effect refusal and confirmed release. This attempt bound nothing; a concurrent request may acquire the key.
Example: true
Idempotent-Replayed"true"Optional
Present and true when returning the stored outcome of an earlier execution.
Example: true

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"service_unavailable","message":"string","details":["string"]}
- code"service_unavailable"Required
  `service_unavailable`: Service unavailable.
  Example: service_unavailable
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

Usage notes# #

Authorization #

Header Parameters #

Request Body #

Response Body #

Usage notes#

Authorization

Header Parameters

Request Body

Response Body