> For the complete documentation index, see [llms.txt](https://developers.unigox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.unigox.com/api-reference/on-ramp.md).

# On Ramp

On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat

## Get on-ramp price estimate

> Get indicative on-ramp pricing (fiat to crypto) without creating a quote.\
> This endpoint is lightweight and does not reserve liquidity.\
> \
> Use this when you need quick pricing discovery before calling \`/partner/onramp/quote\`.\
> Optional filters: \`payment\_method\_slug\`, \`payment\_network\_slug\`, \`provider\_scope\`, \`country\_code\`.\
> This endpoint is indicative and does not apply user/payment-details ownership checks; for executable pricing use quote (which still requires an API key).\
> \
> \*\*Authentication:\*\* None. This is a public endpoint — no API key required (same as \`/partner/liquidity\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[],"paths":{"/api/v1/partner/onramp/estimate":{"post":{"tags":["On-Ramp"],"summary":"Get on-ramp price estimate","description":"Get indicative on-ramp pricing (fiat to crypto) without creating a quote.\nThis endpoint is lightweight and does not reserve liquidity.\n\nUse this when you need quick pricing discovery before calling `/partner/onramp/quote`.\nOptional filters: `payment_method_slug`, `payment_network_slug`, `provider_scope`, `country_code`.\nThis endpoint is indicative and does not apply user/payment-details ownership checks; for executable pricing use quote (which still requires an API key).\n\n**Authentication:** None. This is a public endpoint — no API key required (same as `/partner/liquidity`).\n","operationId":"getOnRampEstimate","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPriceEstimateRequest"}}}},"responses":{"200":{"description":"Estimate retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerPriceEstimateResponse"}}}]}}}},"400":{"description":"Bad request — invalid parameters, missing required fields,\nunsupported cryptocurrency, or invalid provider_scope.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"No offers available for the requested pair/amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"PartnerPriceEstimateRequest":{"type":"object","required":["crypto_currency","fiat_currency"],"oneOf":[{"required":["crypto_amount"]},{"required":["fiat_amount"]}],"properties":{"crypto_currency":{"type":"string","description":"Cryptocurrency code (e.g., USDT, USDC)"},"fiat_currency":{"type":"string","description":"Target fiat currency code (e.g., NGN, USD, EUR)"},"crypto_amount":{"type":"string","description":"Crypto amount to estimate from. Provide exactly one of crypto_amount or fiat_amount."},"fiat_amount":{"type":"string","description":"Fiat amount to estimate from. Provide exactly one of crypto_amount or fiat_amount."},"payment_method_slug":{"type":"string","description":"Optional payment method slug filter to narrow routing"},"payment_network_slug":{"type":"string","description":"Optional payment network slug filter to narrow routing"},"provider_scope":{"type":"string","description":"Optional provider scope filter; defaults to all","enum":["all","licensed_only","p2p_only"]},"country_code":{"type":"string","description":"Optional ISO country code (alpha-2) used for fee/routing context"},"partner_fee_pct":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Optional per-order markup you charge your end user, applied on the same crypto base\nas the platform fee (non-compounding). Percent units: `1` means 1%. Omitting the field\nfrom this request payload — or sending `0` — means no markup; the markup cannot be\nnegative. Fiat-anchored offramp orders have no cap — the deposit grows to cover the\nmarkup. Every other case hits a formula domain bound, not a business cap: onramp\nrejects `partner_fee_pct >= 100` (the withheld or grossed-up fee would consume the\nentire buyer amount, leaving nothing delivered); crypto-anchored offramp rejects it\nwhen the fee would consume the entire pinned deposit.\n\nNote: you send this value as a JSON **string**, but it round-trips as a JSON **number**\nin `fee_breakdown.partner_fee_pct` and in the webhook `data.partner_fee_pct` field —\ndon't parse those as strings.\n\n**Rejection reference:**\n\n| Rejection | `error.code` | HTTP status |\n|---|---|---|\n| `partner_fee_pct` is non-numeric, negative, `NaN`, or `Inf` | `INVALID_REQUEST` | 400 |\n| Onramp: fee would consume the entire buyer amount (`partner_fee_pct >= 100`) | `INVALID_REQUEST` | 400 |\n| Crypto-anchored offramp: fee would consume the entire pinned deposit | `INVALID_REQUEST` | 400 |\n| Fiat-anchored offramp: the computed fee is not a finite amount | `INVALID_REQUEST` | 400 |\n| Crypto-anchored offramp: the carved fee-exclusive gross falls outside the matched offer's min/max | `NO_OFFERS_AVAILABLE` | 409 |\n","default":"0"},"recipient_payout":{"type":"boolean","default":false,"description":"Off-ramp estimate only; the on-ramp estimate ignores it. `true` prices only on the licensed partners a third-party (recipient) payout can be matched to, so the estimate describes a payout to a recipient. It can only narrow the offers priced; the estimate still reserves nothing."},"exclude_delayed_settlement":{"type":"boolean","default":false,"description":"Off-ramp estimate only; the on-ramp estimate ignores it. `true` leaves delayed settlement (T+1) offers out of the price, so when no instant offer covers the amount the estimate answers `409 NO_OFFERS_AVAILABLE`. It changes this estimate only, not what a quote or an order matches."},"recipient_id":{"type":"string","format":"uuid","description":"Off-ramp estimate only. With `recipient_destination_id`, prices a payout to that destination of your recipient: on its own payment method, rail and country, as the quote prices it, so a fee a licensed partner charges for that bank is included. Give both or neither; naming them implies `recipient_payout`. Needs your API key. Errors: `400 INVALID_REQUEST` when only one is given, an id is not a UUID, the destination's currency is not `fiat_currency`, or `payment_method_slug`, `payment_network_slug` or `country_code` differ from the destination's (omit them); `401 UNAUTHORIZED` without a key, or with one that does not authenticate (see the operation's authentication); `404 RECIPIENT_NOT_FOUND` when the recipient or the destination is not yours; `422 THIRD_PARTY_CONTEXT_INVALID` when the destination is not active. The estimate reads the destination and binds nothing."},"recipient_destination_id":{"type":"string","format":"uuid","description":"Off-ramp estimate only. The destination of `recipient_id` the payout would go to; see `recipient_id`."}}},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerPriceEstimateResponse":{"type":"object","properties":{"rate":{"type":"string","description":"Indicative crypto-to-fiat exchange rate"},"crypto_amount":{"type":"string","description":"Estimated total crypto amount — the fee-exclusive gross: the user's amount plus the platform\nfee. Partner-fee-exclusive, except for a crypto-anchored onramp estimate (request declares\n`crypto_amount`): there the amount is sized up so the delivered amount stays exact after the\npartner fee is withheld, so this field includes the markup. A crypto-anchored offramp\nestimate carves both fees out of the pinned deposit instead, so this field and\n`fee_breakdown.platform_fee` both shrink relative to a no-markup request, even though the\nmarkup itself stays out of this field. Every other case is unaffected — the markup is\nreported separately in `fee_breakdown.partner_fee`.\n\nOn-ramp: the end user would receive `crypto_amount − fee_breakdown.platform_fee −\nfee_breakdown.partner_fee` for a fiat-anchored estimate, or exactly this `crypto_amount` for a\ncrypto-anchored estimate. Off-ramp: the amount you would actually fund at initiation is\n`crypto_amount + fee_breakdown.partner_fee`.\n"},"fiat_amount":{"type":"string","description":"Estimated fiat amount"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"payment_method_slug":{"type":"string","description":"Matched payment method slug used for estimate"},"payment_network_slug":{"type":"string","description":"Matched payment network slug used for estimate"},"provider_scope":{"type":"string","description":"Applied provider scope"},"is_indicative":{"type":"boolean","description":"True when response is an estimate and not a reserving quote"},"matching_type":{"type":"string","enum":["network","exact_payment_method"],"description":"How the priced offer matched. `network` — standard payment-network matching. `exact_payment_method` — the offer only matches a counterparty on one of the listed exact payment methods. Omitted when no offer was matched."},"network_matching_available":{"type":"boolean","description":"`true` when `matching_type` is `network`. `false` means this price is reachable only through exact payment-method matching."},"exact_payment_method_matching_offers":{"type":"array","description":"Routes in the same context that only exact payment-method matching can reach — the alternatives to the one this estimate priced. Omitted when there are none. It also travels under `error.details` on a `409 NO_OFFERS_AVAILABLE`, which is where it matters most: the refusal names the routes that would have worked.","items":{"$ref":"#/components/schemas/ExactPaymentMethodMatchingOffer"}},"delayed_settlement":{"type":"boolean","description":"Whether pricing at this amount would currently open a **delayed settlement (T+1)** order. Always present. Indicative, like the numbers: the estimate reserves nothing and the quote matches again, so the class can change either way before the quote. Read the class off the quote (`false` there is binding); the order response is final once a licensed partner has accepted the order. Sent with your credentials, the estimate checks whether Unigox has enabled delayed settlement for you and, until it has, prices instant offers only, as your quotes match. Sent without credentials it does not check, and can report `true` for an amount your quote would refuse."},"settlement_hours":{"type":"integer","nullable":true,"description":"The expected payout window the order would get, counted from the release: the licensed partner's target for the bank payment, not a guaranteed deadline. Rounded to the nearest whole hour and never below `1`. `null` on an instant estimate."},"source_of_funds_required":{"type":"boolean","description":"Whether the order this price would open needs a source-of-funds review before its release: `true` when the price is on a delayed settlement (T+1) offer and the order's USD equivalent (the fiat amount at the current USD rate, falling back to the crypto amount at the current USD rate) is at or above `source_of_funds_threshold_usd`, or cannot be computed. Always present; `false` on an instant estimate and on every on-ramp estimate. Indicative like the rest of the estimate: the order's own `source_of_funds_required` decides."},"source_of_funds_threshold_usd":{"type":"number","description":"The source-of-funds threshold in force, in USD. Present only when `delayed_settlement` is `true`; absent on an instant estimate and on every on-ramp estimate."}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"ExactPaymentMethodMatchingOffer":{"type":"object","description":"One route in the same crypto/fiat/network context that is reachable **only** by exact payment-method matching — a counterparty on this exact method, rather than anyone on the network. Quote with `payment_method_slug` and `payment_network_slug` set to these values to reach it.","properties":{"payment_method_slug":{"type":"string"},"payment_method_name":{"type":"string"},"payment_network_slug":{"type":"string"},"payment_network_name":{"type":"string"},"country_code":{"type":"string","description":"Omitted when the route was resolved without a country scope."},"country_name":{"type":"string","description":"Omitted with `country_code`."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}}}
```

## Get on-ramp quote

> Get a price quote for an on-ramp operation (fiat to crypto). Returns the exchange rate,\
> amounts, and a quote ID that can be used to initiate the order. Quotes expire after 60 seconds.\
> \
> The \`user\_uuid\` is the public UUID returned by \`POST /partner/users\` (the \`id\` field).\
> \
> \*\*Fee structure:\*\* The \`fee\_breakdown\` object shows all fee components transparently:\
> \`platform\_fee\` (our fee in crypto), \`partner\_fee\` (your per-order markup in crypto — declare it\
> by passing \`partner\_fee\_pct\` on the quote/estimate request, where \`1\` means 1%), \`partner\_fee\_pct\`\
> (the percentage applied), and \`total\_fee\` (sum of both). The partner fee is computed on the same\
> crypto base as the platform fee (non-compounding). There's no separate transfer leg for on-ramp:\
> at release the full buyer amount lands in your partner wallet, and the markup is captured by\
> withholding it when the crypto bridges out at send-out (for a crypto-anchored order, the trade is\
> sized up beforehand so the requested amount still arrives net of the withheld fee). The withheld\
> markup stays in your partner wallet: a fee wallet set in the partner dashboard (see the off-ramp\
> quote) does not move it. For a non-custodial (external\_wallet) customer nothing is withheld at\
> send-out: the markup is paid at release, to your fee wallet (or your partner wallet if none is\
> set). What the end\
> user receives: \`crypto\_amount − fee\_breakdown.platform\_fee − fee\_breakdown.partner\_fee\` for a\
> fiat-anchored order, or exactly the \`crypto\_amount\` you requested for a crypto-anchored order.\
> \
> Apply your fee on the \*\*same side\*\* the platform does, or your receipts won't reconcile with our\
> orders. \`crypto\_amount\` in responses and webhooks stays partner-fee-exclusive, with two\
> exceptions: a crypto-anchored onramp order (request declares \`crypto\_amount\`) is sized up so the\
> delivered amount stays exact after the markup is withheld, so \`crypto\_amount\` there includes the\
> markup; a crypto-anchored offramp order (request declares \`crypto\_amount\`) carves both fees out of\
> the pinned deposit, so \`crypto\_amount\` and \`platform\_fee\` both shrink relative to a no-markup\
> request even though the markup itself stays out of \`crypto\_amount\`. Every other case is unaffected\
> — the markup shows only in \`fee\_breakdown\` (and in the funding amount returned by transfer\
> authorization for offramp). Fiat-anchored offramp orders have no cap on the markup — the deposit\
> grows to cover it. Every other case hits a formula domain bound, not a business cap: onramp\
> rejects \`partner\_fee\_pct >= 100\` (the withheld or grossed-up fee would consume the entire buyer\
> amount, leaving nothing delivered); crypto-anchored offramp rejects it when the fee would consume\
> the entire pinned deposit.\
> \
> \*\*Payment method:\*\* Provide \`payment\_method\_slug\` and/or \`payment\_network\_slug\` to narrow routing.\
> If omitted, the best available option for the pair is selected automatically.\
> \
> \*\*KYC requirement:\*\* The customer must be KYC-cleared before you can quote or transact for them.\
> If the customer is not cleared, this endpoint returns \`422 KYC\_NOT\_CLEARED\` and\
> \`error.details.kyc\_status\` carries their current partner-facing KYC status. A customer still in\
> compliance review is reported as \`IN\_PROGRESS\` — treat \`IN\_PROGRESS\` as "not cleared yet" and\
> keep polling \`GET /api/v1/partner/users/{user\_uuid}/verification-status\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerOnRampQuoteRequest":{"type":"object","required":["user_uuid","fiat_currency","crypto_currency"],"oneOf":[{"required":["fiat_amount"]},{"required":["crypto_amount"]}],"properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the end-user (returned by `POST /partner/users` as `id`)"},"fiat_amount":{"type":"string","description":"Fiat amount the end-user will send. Provide exactly one of fiat_amount or crypto_amount."},"crypto_amount":{"type":"string","description":"Crypto amount to receive. Provide exactly one of fiat_amount or crypto_amount."},"fiat_currency":{"type":"string","description":"Source fiat currency code (ISO 4217)"},"crypto_currency":{"type":"string","description":"Target cryptocurrency code (e.g., USDT, USDC)"},"payment_method_slug":{"type":"string","description":"Optional payment method slug to narrow routing"},"payment_network_slug":{"type":"string","description":"Optional payment network slug to narrow routing"},"provider_scope":{"type":"string","description":"Optional provider scope filter; defaults to all","enum":["all","licensed_only","p2p_only"]},"country_code":{"type":"string","description":"Optional ISO 2-letter country code for fee/routing context"},"partner_fee_pct":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Optional per-order markup you charge your end user, applied on the same crypto base\nas the platform fee (non-compounding). Percent units: `1` means 1%. Omitting the field\nfrom this request payload — or sending `0` — means no markup; the markup cannot be\nnegative. Fiat-anchored offramp orders have no cap — the deposit grows to cover the\nmarkup. Every other case hits a formula domain bound, not a business cap: onramp\nrejects `partner_fee_pct >= 100` (the withheld or grossed-up fee would consume the\nentire buyer amount, leaving nothing delivered); crypto-anchored offramp rejects it\nwhen the fee would consume the entire pinned deposit.\n\nNote: you send this value as a JSON **string**, but it round-trips as a JSON **number**\nin `fee_breakdown.partner_fee_pct` and in the webhook `data.partner_fee_pct` field —\ndon't parse those as strings.\n\n**Rejection reference:**\n\n| Rejection | `error.code` | HTTP status |\n|---|---|---|\n| `partner_fee_pct` is non-numeric, negative, `NaN`, or `Inf` | `INVALID_REQUEST` | 400 |\n| Onramp: fee would consume the entire buyer amount (`partner_fee_pct >= 100`) | `INVALID_REQUEST` | 400 |\n| Crypto-anchored offramp: fee would consume the entire pinned deposit | `INVALID_REQUEST` | 400 |\n| Fiat-anchored offramp: the computed fee is not a finite amount | `INVALID_REQUEST` | 400 |\n| Crypto-anchored offramp: the carved fee-exclusive gross falls outside the matched offer's min/max | `NO_OFFERS_AVAILABLE` | 409 |\n","default":"0"}}},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerOnRampQuoteResponse":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid","description":"Unique quote identifier — use this to initiate the order"},"rate":{"type":"string","description":"Fiat-to-crypto exchange rate (fiat units per 1 crypto unit)"},"crypto_amount":{"type":"string","description":"Total crypto amount for the order — the end-user's amount plus the platform fee.\nPartner-fee-exclusive on a fiat-anchored quote (request declared `fiat_amount`): the markup\nis reported separately in `fee_breakdown.partner_fee` and is not added here — the end user\nreceives `crypto_amount − fee_breakdown.platform_fee − fee_breakdown.partner_fee`, withheld\nfrom this amount at bridge send-out. On a crypto-anchored quote (request declared\n`crypto_amount`), the trade is sized up so this field includes the markup, and the end user\nreceives exactly the requested `crypto_amount`, unchanged by the markup.\n"},"fiat_amount":{"type":"string","description":"Fiat amount the end-user sends"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"payment_method_slug":{"type":"string","description":"Matched payment method slug used for this quote"},"payment_network_slug":{"type":"string","description":"Matched payment network slug used for this quote"},"expires_at":{"type":"string","format":"date-time","description":"Quote expiration timestamp (60 seconds from creation)"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/onramp/quote":{"post":{"tags":["On-Ramp"],"summary":"Get on-ramp quote","description":"Get a price quote for an on-ramp operation (fiat to crypto). Returns the exchange rate,\namounts, and a quote ID that can be used to initiate the order. Quotes expire after 60 seconds.\n\nThe `user_uuid` is the public UUID returned by `POST /partner/users` (the `id` field).\n\n**Fee structure:** The `fee_breakdown` object shows all fee components transparently:\n`platform_fee` (our fee in crypto), `partner_fee` (your per-order markup in crypto — declare it\nby passing `partner_fee_pct` on the quote/estimate request, where `1` means 1%), `partner_fee_pct`\n(the percentage applied), and `total_fee` (sum of both). The partner fee is computed on the same\ncrypto base as the platform fee (non-compounding). There's no separate transfer leg for on-ramp:\nat release the full buyer amount lands in your partner wallet, and the markup is captured by\nwithholding it when the crypto bridges out at send-out (for a crypto-anchored order, the trade is\nsized up beforehand so the requested amount still arrives net of the withheld fee). The withheld\nmarkup stays in your partner wallet: a fee wallet set in the partner dashboard (see the off-ramp\nquote) does not move it. For a non-custodial (external_wallet) customer nothing is withheld at\nsend-out: the markup is paid at release, to your fee wallet (or your partner wallet if none is\nset). What the end\nuser receives: `crypto_amount − fee_breakdown.platform_fee − fee_breakdown.partner_fee` for a\nfiat-anchored order, or exactly the `crypto_amount` you requested for a crypto-anchored order.\n\nApply your fee on the **same side** the platform does, or your receipts won't reconcile with our\norders. `crypto_amount` in responses and webhooks stays partner-fee-exclusive, with two\nexceptions: a crypto-anchored onramp order (request declares `crypto_amount`) is sized up so the\ndelivered amount stays exact after the markup is withheld, so `crypto_amount` there includes the\nmarkup; a crypto-anchored offramp order (request declares `crypto_amount`) carves both fees out of\nthe pinned deposit, so `crypto_amount` and `platform_fee` both shrink relative to a no-markup\nrequest even though the markup itself stays out of `crypto_amount`. Every other case is unaffected\n— the markup shows only in `fee_breakdown` (and in the funding amount returned by transfer\nauthorization for offramp). Fiat-anchored offramp orders have no cap on the markup — the deposit\ngrows to cover it. Every other case hits a formula domain bound, not a business cap: onramp\nrejects `partner_fee_pct >= 100` (the withheld or grossed-up fee would consume the entire buyer\namount, leaving nothing delivered); crypto-anchored offramp rejects it when the fee would consume\nthe entire pinned deposit.\n\n**Payment method:** Provide `payment_method_slug` and/or `payment_network_slug` to narrow routing.\nIf omitted, the best available option for the pair is selected automatically.\n\n**KYC requirement:** The customer must be KYC-cleared before you can quote or transact for them.\nIf the customer is not cleared, this endpoint returns `422 KYC_NOT_CLEARED` and\n`error.details.kyc_status` carries their current partner-facing KYC status. A customer still in\ncompliance review is reported as `IN_PROGRESS` — treat `IN_PROGRESS` as \"not cleared yet\" and\nkeep polling `GET /api/v1/partner/users/{user_uuid}/verification-status`.\n","operationId":"getOnRampQuote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOnRampQuoteRequest"}}}},"responses":{"200":{"description":"Quote retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerOnRampQuoteResponse"}}}]}}}},"400":{"description":"Bad request — invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"No offers available for the requested pair","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"The customer is not KYC-cleared. `error.details.kyc_status` carries the customer's current partner-facing KYC status — one of `IN_PROGRESS`, `UNDER_REVIEW`, `PENDING_DOCUMENTS`, `VERIFICATION_REJECTED`, or `NOT_INITIATED`. `UNDER_REVIEW` means a manual compliance review (up to 24h); keep the customer waiting and re-check. The message stays generic.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Initiate on-ramp order

> Initiate an on-ramp order using a previously obtained quote. The quote must still be active\
> (not expired or already used).\
> \
> On success, returns the created order with status \`awaiting\_liquidity\_provider\`.\
> Once a vendor accepts, the order moves to \`awaiting\_vendor\_escrow\_funding\`, then\
> \`awaiting\_fiat\_transfer\` when the crypto is locked in escrow.\
> \
> For an \`external\_wallet\` customer the crypto is released to the customer's own address on\
> completion, and your \`partner\_fee\` is paid to your fee wallet (or your partner wallet if none is\
> set) in the same release transaction.\
> \
> At \`awaiting\_fiat\_transfer\` the partner must call \`confirm-payment-sent\` to advance the order —\
> unless the order's \`fiat\_funding\_source\` is \`own\_account\`. Then \`next\_action\` is\
> \`deposit\_to\_user\_account\`: the customer transfers the order's fiat amount into the fiat account\
> issued to them, that transfer confirms the payment, and \`confirm-payment-sent\` is not used.\
> If the money is already on that account, pay the order from it with\
> \`POST /api/v1/partner/orders/{order\_id}/pay-from-balance\` instead of a new transfer.\
> If the order type is \`payment\_request\`, call \`submit-payer-details\` first before confirming.\
> \
> \*\*KYC requirement:\*\* The customer must be KYC-cleared, as described on \`POST /onramp/quote\`.\
> If they are not, this endpoint returns \`422 KYC\_NOT\_CLEARED\` with the customer's partner-facing\
> status in \`error.details.kyc\_status\`. The check is re-applied as the order moves toward payout.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerInitiateRequest":{"type":"object","required":["quote_id"],"properties":{"quote_id":{"type":"string","format":"uuid","description":"Quote ID from the quote endpoint. Payment details are taken from the quote."},"reference_id":{"type":"string","description":"Optional partner-supplied external reference ID (e.g. your internal order ID). Stored on the order and echoed back in responses."}}},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerInitiateResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier for tracking"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"quote_id":{"type":"string","format":"uuid","description":"Quote ID that was consumed"},"reference_id":{"type":"string","nullable":true,"description":"Partner-supplied external reference ID (echoed from initiate request)"},"order_type":{"type":"string","enum":["offramp","onramp"],"description":"Direction of the order"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"}},"created_at":{"type":"string","format":"date-time"},"recipient_context":{"allOf":[{"$ref":"#/components/schemas/PartnerRecipientContext"}],"nullable":true},"compliance":{"allOf":[{"$ref":"#/components/schemas/PartnerComplianceCase"}],"nullable":true,"description":"Durable case in Unigox compliance review for a third-party payout."},"payout_via_own_account":{"type":"boolean","description":"`true` when this off-ramp will be paid through the customer's own fiat\naccount and then on to the bank you named. Omitted otherwise, never `false`. Read\n`own_account_payout_status` on the order to follow it.\n"}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `fiat_payment_review_started` — the proof is under review\n- `dispute_started` — a dispute was raised on the order\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed`, `crypto_release_pending` — timeline vocabulary. They appear in\n  `timeline[].status`; no order reports either as its own `status`, and filtering on them\n  returns nothing\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation. Like\n  `awaiting_liquidity_provider`, it is reported before a liquidity provider has accepted\n  the order, and `GET /partner/orders?status=` returns the orders that report it\n\n**Delayed settlement (T+1) statuses:**\n\n> Both are unreachable for an ordinary order.\n\n- `settlement_in_progress` — crypto release has started or is confirmed; the order is not\n  yet resolved. This alone does not mean a bank payment has been sent\n- `returned` — the payout went out and the bank sent it back, with no new payout\n  authorization. The crypto is not refunded yet: Unigox arranges another payout attempt, or\n  refunds the crypto and the order reads `cancelled`. A payout the provider cancelled before\n  sending it is not a return\n\nPrecedence on a delayed order, in this order — more than one mark can be set at once:\n\n1. `delayed_settlement_fiat_paid_to_customer_at` set → `completed`\n2. else `delayed_settlement_crypto_refunded_to_customer_at` set → `cancelled`\n3. else `delayed_settlement_fiat_returned_by_bank_at` set **and**\n   `delayed_settlement_fiat_payout_authorized_by_admin_at` `null` → `returned`\n4. else, on a release status → `settlement_in_progress`\n5. before the release, the ordinary mapping applies — a funded delayed order awaiting release is\n   `crypto_received` like any other, and `next_action` is what tells them apart\n\nA return with a fresh authorization on top reads as `settlement_in_progress` (step 4).\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow; the partner pays the vendor and confirms payment sent (`fiat_funding_source: vendor_details`), or the customer transfers into their own fiat account (`own_account`)\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","fiat_payment_review_started","dispute_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","settlement_in_progress","returned","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units) — the fee-exclusive gross: the buy/sell amount plus the\nplatform fee. Partner-fee-exclusive, except for a crypto-anchored onramp order (originally\nquoted with `crypto_amount`): there the amount was sized up so the delivered amount stays\nexact after the partner fee is withheld, so this field includes the markup. A crypto-anchored\nofframp order carves both fees out of the pinned deposit instead, so this field and\n`fee_breakdown.platform_fee` both shrink relative to a no-markup request, even though the\nmarkup itself stays out of this field. Every other case is unaffected — the markup is\nreported separately in `fee_breakdown.partner_fee`.\n\nOn-ramp — what the end user receives: `crypto_amount − fee_breakdown.platform_fee −\nfee_breakdown.partner_fee` for a fiat-anchored order, or exactly this `crypto_amount` for a\ncrypto-anchored order (both fees are withheld at bridge send-out without changing this\nfield). Off-ramp — what the partner funds at transfer authorization:\n`crypto_amount + fee_breakdown.partner_fee`.\n"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change.\n\nOn a **delayed settlement (T+1)** order the release entry reads\n`Crypto released to the liquidity provider, ahead of the payout` under\n`settlement_in_progress`, not `Order completed`: the crypto leaving escrow is the middle of\nthat order's story, not its end. Seven more entries follow it —\n`Crypto transferred to the payout provider`, `Fiat payout authorized`,\n`Fiat payout submitted by the provider` and\n`Fiat payout cancelled by the provider before it was sent` (all `settlement_in_progress`),\n`Fiat paid to the customer` (`completed`), `Fiat returned by the bank` (`returned`) and\n`Crypto refunded to the customer` (`cancelled`). An ordinary order's timeline is unchanged,\nentry for entry.\n\nConsecutive entries are collapsed by status; on a delayed order they are collapsed by status\n**and** description, so the intermediate facts that all carry `settlement_in_progress` each\nkeep their own line.\n\nOnce a payment has come back, or the payout provider cancelled it before sending it, and a\nnew attempt followed, every attempt stays on the timeline and the approval, sending, paid,\nreturn and cancellation entries end in `(attempt N)`, for example\n`Fiat payout authorized (attempt 2)` or `Fiat paid to the customer (attempt 2)`. With a\nsingle attempt there is no suffix. `Crypto transferred to the payout provider` is read from\nthe order's timestamp and leaves the timeline when that timestamp is cleared.\n"}}},"PartnerRecipientContext":{"type":"object","required":["sender_id","recipient_id","recipient_destination_id","sender_recipient_relationship","purpose_of_payment","screening_status"],"properties":{"sender_id":{"type":"string","format":"uuid"},"recipient_id":{"type":"string","format":"uuid"},"recipient_destination_id":{"type":"string","format":"uuid"},"sender_recipient_relationship":{"type":"string"},"purpose_of_payment":{"type":"string"},"purpose_details":{"type":"string"},"screening_status":{"type":"string"}}},"PartnerComplianceCase":{"type":"object","required":["case_id","status","risk_decision","requires_review"],"description":"The compliance record for a third-party payout. In v1 the controls run BEFORE the order is\ncreated, so a payout that fails one is rejected with an error rather than returned as a held\norder — see the error codes in the Third-party payouts guide.\n","properties":{"case_id":{"type":"string","format":"uuid","description":"Identifier of the compliance record — the payout's `quote_id`, so a partner and a Unigox\noperator refer to the same record.\n"},"status":{"type":"string","enum":["authorized"],"description":"v1 emits `authorized`; a rejected payout returns an error instead."},"risk_decision":{"type":"string","enum":["allow"],"description":"v1 emits `allow`; a blocking decision surfaces as an error, not a status."},"requires_review":{"type":"boolean","description":"Always false in v1. Operator review happens Unigox-side over the same record."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/onramp/initiate":{"post":{"tags":["On-Ramp"],"summary":"Initiate on-ramp order","description":"Initiate an on-ramp order using a previously obtained quote. The quote must still be active\n(not expired or already used).\n\nOn success, returns the created order with status `awaiting_liquidity_provider`.\nOnce a vendor accepts, the order moves to `awaiting_vendor_escrow_funding`, then\n`awaiting_fiat_transfer` when the crypto is locked in escrow.\n\nFor an `external_wallet` customer the crypto is released to the customer's own address on\ncompletion, and your `partner_fee` is paid to your fee wallet (or your partner wallet if none is\nset) in the same release transaction.\n\nAt `awaiting_fiat_transfer` the partner must call `confirm-payment-sent` to advance the order —\nunless the order's `fiat_funding_source` is `own_account`. Then `next_action` is\n`deposit_to_user_account`: the customer transfers the order's fiat amount into the fiat account\nissued to them, that transfer confirms the payment, and `confirm-payment-sent` is not used.\nIf the money is already on that account, pay the order from it with\n`POST /api/v1/partner/orders/{order_id}/pay-from-balance` instead of a new transfer.\nIf the order type is `payment_request`, call `submit-payer-details` first before confirming.\n\n**KYC requirement:** The customer must be KYC-cleared, as described on `POST /onramp/quote`.\nIf they are not, this endpoint returns `422 KYC_NOT_CLEARED` with the customer's partner-facing\nstatus in `error.details.kyc_status`. The check is re-applied as the order moves toward payout.\n","operationId":"initiateOnRamp","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerInitiateRequest"}}}},"responses":{"200":{"description":"On-ramp order created. Success answers `200`, not `201`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerInitiateResponse"}}}]}}}},"400":{"description":"Bad request — missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Quote not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"Quote expired or already used. Also `WALLET_NOT_LINKED` (an `external_wallet` customer with no linked address) and `OPERATION_NOT_ALLOWED` (a partner fee on an `external_wallet` customer's order while your partner account has neither a fee wallet nor a partner wallet to receive it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"The customer is not KYC-cleared. `error.details.kyc_status` carries the customer's current partner-facing KYC status — one of `IN_PROGRESS`, `UNDER_REVIEW`, `PENDING_DOCUMENTS`, `VERIFICATION_REJECTED`, or `NOT_INITIATED`. `UNDER_REVIEW` means a manual compliance review (up to 24h); keep the customer waiting and re-check. The message stays generic.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Submit payer details

> Submit the end-user's payment details for a \`payment\_request\` on-ramp order.\
> Only required when the order type is \`payment\_request\` — regular on-ramp orders do not need this step.\
> \
> \*\*Order types:\*\*\
> \- \*\*Regular on-ramp\*\* — the vendor sends fiat to the end-user directly. No payer details needed.\
> &#x20; The partner receives vendor payment details in the \`vendor\_payment\_details\` field of \`GET /orders/:id\`\
> &#x20; and forwards them to the end-user to initiate the transfer.\
> \- \*\*\`payment\_request\` on-ramp\*\* — the vendor sends a payment request (e.g. M-Pesa push) to the end-user.\
> &#x20; The end-user's account details must be submitted here first so the vendor knows where to send the request.\
> &#x20; Check \`payment\_request: true\` in the order response to identify this type.\
> \
> Call this endpoint after initiating the order and before calling \`confirm-payment-sent\`.\
> The order must be in \`awaiting\_fiat\_transfer\` status.\
> \
> Provide either a \`payment\_details\_id\` (referencing a previously saved payment profile) or\
> an inline \`payment\_details\` object with the payer's account information.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"SubmitPayerDetailsRequest":{"type":"object","description":"Submit the payer's payment details for a `payment_request` on-ramp order.\nProvide exactly one of `payment_details_id` (saved profile) or `payment_details` (inline object).\n","oneOf":[{"required":["payment_details_id"],"properties":{"payment_details_id":{"type":"integer","format":"int64","description":"ID of a previously saved payment profile for the end-user"}}},{"required":["payment_details"],"properties":{"payment_details":{"type":"object","required":["payment_method_id","payment_network_id","details"],"properties":{"payment_method_id":{"type":"integer","format":"int64","description":"Payment method ID"},"payment_network_id":{"type":"integer","format":"int64","description":"Payment network ID"},"details":{"type":"object","description":"Payer's account details (fields depend on payment method)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/submit-payer-details":{"post":{"tags":["On-Ramp"],"summary":"Submit payer details","description":"Submit the end-user's payment details for a `payment_request` on-ramp order.\nOnly required when the order type is `payment_request` — regular on-ramp orders do not need this step.\n\n**Order types:**\n- **Regular on-ramp** — the vendor sends fiat to the end-user directly. No payer details needed.\n  The partner receives vendor payment details in the `vendor_payment_details` field of `GET /orders/:id`\n  and forwards them to the end-user to initiate the transfer.\n- **`payment_request` on-ramp** — the vendor sends a payment request (e.g. M-Pesa push) to the end-user.\n  The end-user's account details must be submitted here first so the vendor knows where to send the request.\n  Check `payment_request: true` in the order response to identify this type.\n\nCall this endpoint after initiating the order and before calling `confirm-payment-sent`.\nThe order must be in `awaiting_fiat_transfer` status.\n\nProvide either a `payment_details_id` (referencing a previously saved payment profile) or\nan inline `payment_details` object with the payer's account information.\n","operationId":"submitPayerDetails","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID returned by the initiate endpoint","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitPayerDetailsRequest"}}}},"responses":{"200":{"description":"Payer details submitted successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"}}}}}]}}}},"400":{"description":"Bad request — invalid or missing payer details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"Order is not in the correct status or not a payment_request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Confirm fiat payment sent

> Confirm that the end-user has initiated the fiat payment to the vendor.\
> This advances the order from \`awaiting\_fiat\_transfer\` to \`fiat\_transfer\_pending\`,\
> signalling to the vendor that the fiat is on its way.\
> \
> For \`payment\_request\` orders, call \`submit-payer-details\` first.\
> No request body required.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/confirm-payment-sent":{"post":{"tags":["On-Ramp"],"summary":"Confirm fiat payment sent","description":"Confirm that the end-user has initiated the fiat payment to the vendor.\nThis advances the order from `awaiting_fiat_transfer` to `fiat_transfer_pending`,\nsignalling to the vendor that the fiat is on its way.\n\nFor `payment_request` orders, call `submit-payer-details` first.\nNo request body required.\n","operationId":"confirmPaymentSent","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment confirmed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"Order is not in awaiting_fiat_transfer status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Pay an on-ramp from the customer's account balance

> Pays an on-ramp order with \`fiat\_funding\_source: own\_account\` out of money already standing on\
> the customer's fiat account, instead of a new transfer. The order's \`fiat\_amount\` is taken from\
> the account named in the order's \`fiat\_account\_id\` (or, for an order opened before the account\
> was issued, the customer's open account in that currency), and the order then continues exactly\
> as if that amount had just arrived.\
> \
> Offered in \`allowed\_actions\` as \`pay-from-balance\` while the order is \`awaiting\_fiat\_transfer\`\
> and its fiat has not been collected. Read the account's \`balances\` first: \`available\` is what can\
> be spent. No request body.\
> \
> Repeating the call for the same order never takes the money twice: a payment already taken is\
> answered from its record. If a transfer has already funded the order, the call is refused.\
> \
> \*\*KYC requirement:\*\* the customer must still be KYC-cleared; otherwise \`422 KYC\_NOT\_CLEARED\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerOrderResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"next_action":{"type":"string","description":"The action the partner **must** perform to advance the order. The key is **absent**\nwhen no action is required at this stage — the order is waiting for the\ncounterparty or for an automated system step — and is never sent as `null`.\n\nPossible values:\n- `authorize_crypto_transfer` — partner must authorize escrow funding\n- `confirm_fiat_received` — partner must confirm they received the fiat payment\n- `request_new_quote` — price changed, partner must request a new quote\n- `update_kyc_address` — address fields are required for EUR/AUD/GBP payouts; see `action_required` for the endpoint and fields to submit\n- `authorize_refund` — the order ended without a payout and its crypto is still in escrow; only your\n  signature can send it back. Note that this appears on an order whose `status` is `cancelled`, which\n  is the one case where a terminal status still needs something from you\n- `deposit_to_user_account` — an on-ramp order with `fiat_funding_source: own_account` is waiting for the\n  customer to transfer the order's fiat amount into the fiat account issued to them. The transfer\n  itself confirms the payment; there is nothing to call. If the money is already on the account,\n  `pay-from-balance` is in `allowed_actions` and pays the order from it\n- `sign_settlement_consent` — a **delayed settlement (T+1)** order remains at `crypto_received`\n  and nobody has signed the release yet\n- `submit_source_of_funds` — consent is stored and a required source-of-funds case is\n  incomplete, including an existing case below the current threshold\n- `await_review` — consent is stored and the order is waiting for Unigox document review,\n  the licensed partner's payment check, or release processing. Do not submit another signature\n- absent — no required action (waiting for buyer or system). On a funded delayed order awaiting release\n  the key is absent when the order is held for review, or a payout of yours failed and a\n  refund is under way\n\nOnce consent_deadline_at has passed, these reads no longer request a consent signature,\neven if the order status has not changed yet.\nThe list (`GET /api/v1/partner/orders`) reads the consent from the order record and can show\n`await_review`, for up to two minutes, for a consent call that was cut off before your signature\nwas stored. After a\ntimeout, read the single order (`GET /api/v1/partner/orders/{order_id}`) before you decide\nwhether to send the signature again. If a lookup behind the T+1 hint fails, both reads fall\nback to `sign_settlement_consent`.\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address","authorize_refund","deposit_to_user_account","sign_settlement_consent","submit_source_of_funds","await_review"]},"action_required":{"type":"object","nullable":true,"description":"Present when the order needs partner intervention before it can proceed.\nContains machine-readable type, human-readable message, the API endpoint to call,\nand the fields to provide. Null/omitted when no action is needed.\n","required":["type","message"],"properties":{"type":{"type":"string","description":"Machine-readable action identifier"},"message":{"type":"string","description":"Human-readable explanation of what is needed and why"},"endpoint":{"type":"string","description":"API endpoint to call to resolve this action"},"fields":{"type":"array","description":"Fields the partner needs to provide","items":{"type":"object","required":["field","label"],"properties":{"field":{"type":"string","description":"API field name"},"label":{"type":"string","description":"Human-readable description of the field"}}}}}},"allowed_actions":{"type":"array","items":{"type":"string"},"description":"List of API actions the partner **can** perform at the current status. An action\nmay be present here even when `next_action` is absent — meaning it is optional.\n\nNotable case: `confirm-fiat-received` appears at both `crypto_received` and\n`awaiting_fiat_received_confirmation`. At `crypto_received` it is a **fast-track**:\nif you already know the fiat has arrived via your own systems, you can confirm\nimmediately. Otherwise, wait for the buyer's proof flow to complete — the order\nwill reach `awaiting_fiat_received_confirmation` automatically.\n\nStatus-to-actions mapping:\n- `created` → `[\"cancel\"]`\n- `awaiting_liquidity_provider` → `[\"cancel\"]`\n- `awaiting_crypto_transfer_authorization` → `[\"authorize-crypto-transfer\", \"cancel\"]`\n- `crypto_transfer_authorization_pending` → `[]` (the transfer is in flight; cancel is refused)\n- `crypto_received` → `[\"confirm-fiat-received\"]` (optional fast-track)\n- `fiat_payment_started` → `[\"confirm-fiat-received\"]` (optional fast-track after buyer proof submission)\n- `awaiting_fiat_received_confirmation` → `[\"confirm-fiat-received\"]` (required)\n- `fiat_received_confirmed`, `crypto_release_pending`, `completed`, `failed` → `[]`\n- `cancelled` → `[]`, **except** when the order's crypto is still sitting in escrow: then\n  `[\"authorize-refund\"]`. An off-ramp order that stops after funding — expired payment window,\n  declined payment proof, returned bank payment, dispute resolved for the seller — reads as\n  `cancelled` like every other stopped order, and the escrow is a 2-of-3 Safe your key is an\n  owner of. This is the only thing that tells the two apart, so poll it on `cancelled` orders\n  rather than assuming a cancelled order is finished with. `next_action` is\n  `authorize_refund` and `action_required` names the endpoint at the same time.\n\nOn-ramp orders with `fiat_funding_source: own_account` never offer `confirm-payment-sent`: the\ntransfer into the customer's own account is the confirmation. At `awaiting_fiat_transfer` they\noffer `[\"pay-from-balance\"]` instead, until the order's fiat has been collected. A `completed`\norder paid from the balance whose crypto hand-over has not finished also offers\n`[\"pay-from-balance\"]`: calling it again retries the hand-over and never takes the money twice.\n\nOn a funded **delayed settlement (T+1)** order awaiting release whose crypto you hold,\n`confirm-fiat-received` is removed — the endpoint behind it refuses a delayed order — and\n`[\"settlement-consent\", \"cancel\"]` take its place.\n\n`cancel` is available only while the order awaits release; the endpoint is the ordinary\n`POST /api/v1/partner/orders/{order_id}/cancel`.\n\nBoth are withdrawn once the consent is signed, and then answer\n`409 OPERATION_NOT_ALLOWED`. The list reads the consent from the order record, so a list row\ncan already show them withdrawn, for up to two minutes, for a consent call that was cut off\nbefore your signature was\nstored. After a timeout, read the single order (`GET /api/v1/partner/orders/{order_id}`)\nbefore you decide whether to send the signature again.\n\nOn a funded delayed order awaiting release that is **held** — Unigox holds it for a check, or a\npayout failed and a refund is under way — `next_action` is omitted and no consent is accepted.\n`confirm-fiat-received` is absent there too, because that endpoint refuses every delayed\norder. An `authorize-refund` that is genuinely owed still appears.\nCustody outranks the mapping above: on a **widget order** — one your customer created\nthrough the embedded widget under your `widgetKey` — this is `[]` at every status,\nbecause the crypto is the end user's and every action endpoint answers `404\nORDER_NOT_FOUND` for it.\n"},"fiat_funding_source":{"type":"string","enum":["vendor_details","own_account"],"description":"On-ramp orders only. Where the fiat for this order is paid:\n- `vendor_details` — to the vendor's bank account in `vendor_payment_details`; then call\n  `confirm-payment-sent`.\n- `own_account` — into the fiat account you issued to the customer, named by\n  `fiat_account_id`. There are no `vendor_payment_details` and no `confirm-payment-sent`:\n  the transfer landing on the customer's account is matched to the order by amount and the\n  order proceeds on its own.\n\nRead it on every order rather than assuming one or the other.\n"},"fiat_account_id":{"type":"string","format":"uuid","description":"On an `own_account` order: the fiat account the customer transfers into. The same id the\nFiat Accounts endpoints take, so the deposit that funds this order can be found on that\naccount's transactions carrying this order's id.\nOn an off-ramp with `payout_via_own_account: true`: the customer's fiat account the money\ngoes through, when it is one you can address by id; omitted otherwise.\n"},"payout_via_own_account":{"type":"boolean","description":"`true` on an off-ramp paid through the customer's own fiat account: the liquidity provider\npays the customer's account and Unigox then pays the money on to the bank you named, both in\nthe customer's name. EUR and GBP off-ramps to the customer's own `payment_details` are paid\nthis way wherever customer fiat accounts are active for your partner in that currency; when\nthey cannot be, the quote is refused (`FIAT_ACCOUNT_OPENING`, `FIAT_ACCOUNT_REQUIRED`,\n`FIAT_ACCOUNTS_NOT_ENABLED`) unless a liquidity provider that pays banks directly takes the\norder. Omitted on every other order, never `false`. If you do not call\n`confirm-fiat-received`, the order is confirmed once Unigox has matched the money on the\ncustomer's account. That payment into the account does not send\n`fiat_account.deposit.received`.\n"},"own_account_payout_status":{"type":"string","enum":["awaiting_credit","in_progress","sent_to_bank","under_review","held","left_on_account"],"description":"Off-ramp paid through the customer's own fiat account only (`payout_via_own_account: true`):\nwhere the onward payment, from that account to the bank you named, stands. `status` describes\nthe provider's payment into the customer's account, so an order can be `completed` while this\nstill says the money has not reached the bank.\n- `awaiting_credit` — nothing has landed on the customer's account for this order yet.\n- `in_progress` — the money landed; the onward payment is queued, being sent, or being retried.\n- `sent_to_bank` — the money was sent on to the bank you named.\n- `under_review` — the onward payment ended without a clear result; Unigox checks it.\n- `held` — the money is on the customer's account and is not moving on by itself; contact Unigox.\n- `left_on_account` — Unigox decided the money stays on the customer's account.\n\nOmitted on other orders, and when the state cannot be read at that moment.\n"},"crypto_transfer_authorization_seconds_left":{"type":"integer","format":"int64","nullable":true,"description":"Remaining seconds to authorize crypto transfer while order is in\n`awaiting_crypto_transfer_authorization` / `crypto_transfer_authorization_pending`.\n`null` for all other statuses.\n"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"},"description":"Chronological list of status changes"},"has_fiat_settlement_notification":{"type":"boolean","description":"Whether the matched liquidity provider sends fiat settlement notifications.\nWhen `true`, the order will complete automatically when fiat is delivered.\nWhen `false`, you must call `confirm-fiat-received`. You can call\n`confirm-fiat-received` at any time regardless of this value, except on a delayed\nsettlement (T+1) order, which refuses it. `false` on every order no liquidity provider\nhas accepted yet, T+1 included; a T+1 order reads `true` from its acceptance on.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","enum":["offramp","onramp"],"description":"Order type. Present on every order, including one no liquidity provider has accepted yet.\n- `offramp` — sell crypto for fiat\n- `onramp` — buy crypto with fiat\n"},"vendor_payment_details":{"type":"object","nullable":true,"description":"Vendor's payment details for the end-user to send fiat to.\nPresent only for on-ramp orders at `awaiting_fiat_transfer` status and beyond.\n","properties":{"payment_method_name":{"type":"string"},"payment_network_name":{"type":"string"},"details":{"type":"object","description":"Payment method-specific fields (e.g. account_number, phone)"}}},"payment_request":{"type":"boolean","nullable":true,"description":"`true` if the vendor uses payment request flow — the partner must call\n`submit-payer-details` before `confirm-payment-sent`.\n"},"send_out_tx_hash":{"type":"string","nullable":true,"description":"Destination-chain transaction hash after a send-out completes.\nPresent only for on-ramp orders with `send_out_completed` status.\n"},"payment_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"On-ramp only: the moment the order can be cancelled for want of the customer's fiat.\nTell the customer to pay before it. The order is cancelled shortly after it (`cancelled`,\n\"Payment window expired\"): on your next read of the order, and an `own_account` order\nwithin about 20 minutes even if nobody reads it. A transfer that arrives after this moment but before the cancellation may\nstill complete the order; that is possible, not guaranteed. One that arrives after the\ncancellation stays on the customer's account and can be used with `pay-from-balance` on a\nnew order. Extended along with the window.\nSet while the order is `awaiting_fiat_transfer`, `null` otherwise — and always `null`\non an off-ramp, and on an order held for manual handling (it does not expire). UTC.\n"},"recipient_context":{"allOf":[{"$ref":"#/components/schemas/PartnerRecipientContext"}],"nullable":true,"description":"Immutable third-party recipient context; absent for self-payout and on-ramp."},"compliance":{"allOf":[{"$ref":"#/components/schemas/PartnerComplianceCase"}],"nullable":true,"description":"Current durable compliance-case state for a third-party payout."},"delayed_settlement":{"type":"boolean","description":"Whether this order settles **T+1**: the crypto leaves escrow before the fiat is paid.\nYour release signature authorises it to leave and Unigox performs the release; the fiat\nis expected within `settlement_hours` of it (a target, not a deadline). Present on every\norder, on-ramp included, along\nwith the other T+1 fields below. T+1 timestamps and the window are null on instant\norders. The current numeric source-of-funds threshold is still returned.\n\nProvisional until a licensed partner accepts the order. While an order quoted T+1 waits for\none, it follows the offer the order is currently offered to, so it can change: it reads\n`false` between offers and on an instant offer. Once such an order stops waiting without\nbeing accepted (you cancelled it, or no licensed partner accepted it), it keeps `true`,\nwith `settlement_hours` `null`. Fixed from acceptance.\n"},"settlement_hours":{"type":"integer","nullable":true,"description":"The expected payout window, counted from the release — not from the order. It is the licensed partner's target for the bank payment, not a guaranteed deadline: nothing happens automatically when it passes. Rounded to the nearest whole hour and never below `1`. `null` on an instant order."},"consent_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Funding time plus the consent window. After expiry, release is blocked and the expiry\nprocess starts the refund flow. Set while awaiting release, `null` otherwise.\n"},"payout_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Release time plus the expected window; `settlement_hours` is that window rounded to whole\nhours. When the payment is expected by, not a deadline: the order does not change and no\nevent is sent when it passes. `null` until the crypto has left escrow.\n"},"delayed_settlement_crypto_sent_to_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto left the licensed partner's wallet for the payout provider. Set at the latest when Unigox authorizes the bank payment. No refund of the crypto is possible while it is set. Cleared when Unigox withdraws a record made by mistake, which it can do only while no payment has been authorized, sent, paid or returned, and when it refunds the crypto after a returned payment."},"delayed_settlement_fiat_payout_authorized_by_admin_at":{"type":"string","format":"date-time","nullable":true,"description":"Unigox authorized the licensed partner to send the bank payment. Never set before `delayed_settlement_crypto_sent_to_provider_at`: the authorization sets that one too when it is still `null`. Cleared by a bank return, and when the payout provider cancels the payment before sending it; Unigox then authorizes a new attempt."},"delayed_settlement_fiat_payout_submitted_by_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"Submission of the bank payment was recorded; recipient payment is not yet confirmed."},"delayed_settlement_fiat_paid_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The fiat reached the recipient. This is the real completion of a delayed order."},"delayed_settlement_fiat_returned_by_bank_at":{"type":"string","format":"date-time","nullable":true,"description":"The payout went out and the bank sent it back. Set together with clearing the paid, submitted and authorized marks. Mutually exclusive with `delayed_settlement_fiat_paid_to_customer_at`. A payment the payout provider cancelled before sending it is not a return and does not set it."},"delayed_settlement_crypto_refunded_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto went back to the wallet that funded the escrow (yours, on an order whose crypto you hold) instead of being paid out. Reachable while `delayed_settlement_crypto_sent_to_provider_at` is `null`, or after a returned payment when Unigox gives the payout up; that refund clears `delayed_settlement_crypto_sent_to_provider_at`."},"source_of_funds_required":{"type":"boolean","description":"Whether review applies by amount or an existing source-of-funds case. Can stay true after approval or completion; use case status and next_action for required action. False for instant orders. Always present."},"source_of_funds_threshold_usd":{"type":"number","description":"Current configured source-of-funds threshold in USD, not a historical snapshot. Always present, including on instant orders. Current policy is USD 50,000 inclusive."},"settlement_refund_reason":{"type":"string","description":"Why a delayed order ended without a payout. Omitted — not empty — when the order has not\nended that way, or when none of the six applies; an absence means no reason was recorded\nand never stands in for one of them.\n\n- `refunded_after_release` — the crypto had been released to the licensed partner and\n  was sent back: before it reached the payout provider, or after a payment came back and\n  Unigox gave the payout up. No payment reached the customer; the order reads `cancelled`\n- `dossier_rejected` — a reviewer refused the source-of-funds case\n- `consent_window_expired` — the consent was never signed and the window ran out\n- `not_released_in_time` — the consent **was** signed and the window still ran out,\n  because Unigox did not release the crypto in time. This one is ours, not the\n  customer's\n- `cancelled_by_customer` — the order was cancelled on your side before release\n- `cancelled_by_licensed_partner` — the licensed partner declined the order before the\n  release was signed\n\nRead in that order: a refund after the release outranks a refusal, which outranks an\nexpired window, which outranks a cancellation.\n","enum":["refunded_after_release","dossier_rejected","consent_window_expired","not_released_in_time","cancelled_by_customer","cancelled_by_licensed_partner"]}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `fiat_payment_review_started` — the proof is under review\n- `dispute_started` — a dispute was raised on the order\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed`, `crypto_release_pending` — timeline vocabulary. They appear in\n  `timeline[].status`; no order reports either as its own `status`, and filtering on them\n  returns nothing\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation. Like\n  `awaiting_liquidity_provider`, it is reported before a liquidity provider has accepted\n  the order, and `GET /partner/orders?status=` returns the orders that report it\n\n**Delayed settlement (T+1) statuses:**\n\n> Both are unreachable for an ordinary order.\n\n- `settlement_in_progress` — crypto release has started or is confirmed; the order is not\n  yet resolved. This alone does not mean a bank payment has been sent\n- `returned` — the payout went out and the bank sent it back, with no new payout\n  authorization. The crypto is not refunded yet: Unigox arranges another payout attempt, or\n  refunds the crypto and the order reads `cancelled`. A payout the provider cancelled before\n  sending it is not a return\n\nPrecedence on a delayed order, in this order — more than one mark can be set at once:\n\n1. `delayed_settlement_fiat_paid_to_customer_at` set → `completed`\n2. else `delayed_settlement_crypto_refunded_to_customer_at` set → `cancelled`\n3. else `delayed_settlement_fiat_returned_by_bank_at` set **and**\n   `delayed_settlement_fiat_payout_authorized_by_admin_at` `null` → `returned`\n4. else, on a release status → `settlement_in_progress`\n5. before the release, the ordinary mapping applies — a funded delayed order awaiting release is\n   `crypto_received` like any other, and `next_action` is what tells them apart\n\nA return with a fresh authorization on top reads as `settlement_in_progress` (step 4).\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow; the partner pays the vendor and confirms payment sent (`fiat_funding_source: vendor_details`), or the customer transfers into their own fiat account (`own_account`)\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","fiat_payment_review_started","dispute_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","settlement_in_progress","returned","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units) — the fee-exclusive gross: the buy/sell amount plus the\nplatform fee. Partner-fee-exclusive, except for a crypto-anchored onramp order (originally\nquoted with `crypto_amount`): there the amount was sized up so the delivered amount stays\nexact after the partner fee is withheld, so this field includes the markup. A crypto-anchored\nofframp order carves both fees out of the pinned deposit instead, so this field and\n`fee_breakdown.platform_fee` both shrink relative to a no-markup request, even though the\nmarkup itself stays out of this field. Every other case is unaffected — the markup is\nreported separately in `fee_breakdown.partner_fee`.\n\nOn-ramp — what the end user receives: `crypto_amount − fee_breakdown.platform_fee −\nfee_breakdown.partner_fee` for a fiat-anchored order, or exactly this `crypto_amount` for a\ncrypto-anchored order (both fees are withheld at bridge send-out without changing this\nfield). Off-ramp — what the partner funds at transfer authorization:\n`crypto_amount + fee_breakdown.partner_fee`.\n"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change.\n\nOn a **delayed settlement (T+1)** order the release entry reads\n`Crypto released to the liquidity provider, ahead of the payout` under\n`settlement_in_progress`, not `Order completed`: the crypto leaving escrow is the middle of\nthat order's story, not its end. Seven more entries follow it —\n`Crypto transferred to the payout provider`, `Fiat payout authorized`,\n`Fiat payout submitted by the provider` and\n`Fiat payout cancelled by the provider before it was sent` (all `settlement_in_progress`),\n`Fiat paid to the customer` (`completed`), `Fiat returned by the bank` (`returned`) and\n`Crypto refunded to the customer` (`cancelled`). An ordinary order's timeline is unchanged,\nentry for entry.\n\nConsecutive entries are collapsed by status; on a delayed order they are collapsed by status\n**and** description, so the intermediate facts that all carry `settlement_in_progress` each\nkeep their own line.\n\nOnce a payment has come back, or the payout provider cancelled it before sending it, and a\nnew attempt followed, every attempt stays on the timeline and the approval, sending, paid,\nreturn and cancellation entries end in `(attempt N)`, for example\n`Fiat payout authorized (attempt 2)` or `Fiat paid to the customer (attempt 2)`. With a\nsingle attempt there is no suffix. `Crypto transferred to the payout provider` is read from\nthe order's timestamp and leaves the timeline when that timestamp is cleared.\n"}}},"PartnerRecipientContext":{"type":"object","required":["sender_id","recipient_id","recipient_destination_id","sender_recipient_relationship","purpose_of_payment","screening_status"],"properties":{"sender_id":{"type":"string","format":"uuid"},"recipient_id":{"type":"string","format":"uuid"},"recipient_destination_id":{"type":"string","format":"uuid"},"sender_recipient_relationship":{"type":"string"},"purpose_of_payment":{"type":"string"},"purpose_details":{"type":"string"},"screening_status":{"type":"string"}}},"PartnerComplianceCase":{"type":"object","required":["case_id","status","risk_decision","requires_review"],"description":"The compliance record for a third-party payout. In v1 the controls run BEFORE the order is\ncreated, so a payout that fails one is rejected with an error rather than returned as a held\norder — see the error codes in the Third-party payouts guide.\n","properties":{"case_id":{"type":"string","format":"uuid","description":"Identifier of the compliance record — the payout's `quote_id`, so a partner and a Unigox\noperator refer to the same record.\n"},"status":{"type":"string","enum":["authorized"],"description":"v1 emits `authorized`; a rejected payout returns an error instead."},"risk_decision":{"type":"string","enum":["allow"],"description":"v1 emits `allow`; a blocking decision surfaces as an error, not a status."},"requires_review":{"type":"boolean","description":"Always false in v1. Operator review happens Unigox-side over the same record."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/pay-from-balance":{"post":{"tags":["On-Ramp"],"summary":"Pay an on-ramp from the customer's account balance","description":"Pays an on-ramp order with `fiat_funding_source: own_account` out of money already standing on\nthe customer's fiat account, instead of a new transfer. The order's `fiat_amount` is taken from\nthe account named in the order's `fiat_account_id` (or, for an order opened before the account\nwas issued, the customer's open account in that currency), and the order then continues exactly\nas if that amount had just arrived.\n\nOffered in `allowed_actions` as `pay-from-balance` while the order is `awaiting_fiat_transfer`\nand its fiat has not been collected. Read the account's `balances` first: `available` is what can\nbe spent. No request body.\n\nRepeating the call for the same order never takes the money twice: a payment already taken is\nanswered from its record. If a transfer has already funded the order, the call is refused.\n\n**KYC requirement:** the customer must still be KYC-cleared; otherwise `422 KYC_NOT_CLEARED`.\n","operationId":"payOnRampFromBalance","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The fiat was taken from the balance. The order, as `GET /api/v1/partner/orders/{order_id}` returns it.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerOrderResponse"}}}]}}}},"400":{"description":"`INVALID_REQUEST` — malformed `order_id`, or the order is not an on-ramp.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"`ORDER_NOT_FOUND`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"- `OPERATION_NOT_ALLOWED` — the order is not paid from the customer's own account, a transfer already funds it, or part of the balance is under review and the rest does not cover the order.\n- `INVALID_STATUS` — the order is not waiting for its fiat, or its payment window has closed.\n- `FIAT_ACCOUNT_REQUIRED` — the customer has no open fiat account this order can be paid from.\nNothing was taken.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"- `INSUFFICIENT_BALANCE` — the available balance does not cover the order's `fiat_amount`.\n- `KYC_NOT_CLEARED` — the customer is no longer cleared.\nNothing was taken.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR` — read the order before retrying; a retry never takes the money twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"502":{"description":"`INTERNAL_ERROR` from the gateway — the order service could not be reached or failed. The payment may have been taken: read the order (`GET /api/v1/partner/orders/{order_id}`) before retrying; a retry never takes the money twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"503":{"description":"`PAY_FROM_BALANCE_UNAVAILABLE` — not available right now. Nothing was taken; the customer can still transfer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"504":{"description":"`INTERNAL_ERROR` from the gateway — the order service did not answer within 90 s. The payment may still have been taken: read the order before retrying; a retry never takes the money twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## List send-out destinations

> Lists where a completed on-ramp order of the given crypto can be withdrawn with\
> \`bridge-authorization-parameters\` / \`authorize-bridge\`. Same catalog and names as the\
> withdraw screen on unigox.com: the token is the order's crypto, and each route is a chain\
> that carries that token. Pass \`destination\_chain\` exactly as listed (or the \`chain\_id\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/send-out/routes":{"get":{"tags":["On-Ramp"],"summary":"List send-out destinations","description":"Lists where a completed on-ramp order of the given crypto can be withdrawn with\n`bridge-authorization-parameters` / `authorize-bridge`. Same catalog and names as the\nwithdraw screen on unigox.com: the token is the order's crypto, and each route is a chain\nthat carries that token. Pass `destination_chain` exactly as listed (or the `chain_id`).\n","operationId":"getSendOutRoutes","parameters":[{"name":"crypto","in":"query","required":true,"description":"The order's crypto code, e.g. `USDT` or `USDC`","schema":{"type":"string"}}],"responses":{"200":{"description":"Destination chains for that crypto","content":{"application/json":{}}},"400":{"description":"Missing crypto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Get send-out authorization parameters

> After an on-ramp order reaches \`completed\` status (crypto on your partner wallet), the partner\
> can optionally initiate a cross-chain send-out to transfer the USDT to an external network\
> (e.g. Arbitrum).\
> \
> \`partner\_wallet\` customers only. For an \`external\_wallet\` customer the crypto is released to\
> the customer's own address, and they move it onward with\
> \`POST /api/v1/partner/users/{user\_uuid}/withdrawals/quote\`; this endpoint answers\
> \`422 WALLET\_TYPE\_MISMATCH\`.\
> \
> This endpoint returns the EIP-712 \`ForwardRequest\` parameters required to authorize the\
> transfer. The partner must sign the request locally and submit the signature to\
> \`POST /api/v1/partner/orders/{order\_id}/authorize-bridge\`.\
> \
> \*\*Prerequisites:\*\*\
> \- Order status must be \`completed\` (internal: \`escrow\_released\_to\_buyer\`)\
> \- \`destination\_chain\` is a chain name exactly as \`GET /partner/send-out/routes\` lists it (e.g. \`Arbitrum One\`, \`BNB Smart Chain\`, case-insensitive) or its \`chain\_id\`\
> \- The order's own crypto is sent; only chains that carry that token are accepted\
> \- \`destination\_address\` must be valid for the chain type (EVM \`0x…\`, Tron \`T…\`, Solana, TON)\
> \
> \*\*Response includes:\*\*\
> \- \`forward\_request\` — pre-filled EIP-712 ForwardRequest object to sign\
> \- \`eip712\_domain\` — domain parameters for EIP-712 signing\
> \- \`quote\_id\` — bridge quote ID embedded in the transfer calldata\
> \- \`to\_amount\` — estimated USDT amount to be received on the destination chain (atomic units)\
> \- \`forwarder\_nonce\` — current on-chain nonce for your partner wallet<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/bridge-authorization-parameters":{"get":{"tags":["On-Ramp"],"summary":"Get send-out authorization parameters","description":"After an on-ramp order reaches `completed` status (crypto on your partner wallet), the partner\ncan optionally initiate a cross-chain send-out to transfer the USDT to an external network\n(e.g. Arbitrum).\n\n`partner_wallet` customers only. For an `external_wallet` customer the crypto is released to\nthe customer's own address, and they move it onward with\n`POST /api/v1/partner/users/{user_uuid}/withdrawals/quote`; this endpoint answers\n`422 WALLET_TYPE_MISMATCH`.\n\nThis endpoint returns the EIP-712 `ForwardRequest` parameters required to authorize the\ntransfer. The partner must sign the request locally and submit the signature to\n`POST /api/v1/partner/orders/{order_id}/authorize-bridge`.\n\n**Prerequisites:**\n- Order status must be `completed` (internal: `escrow_released_to_buyer`)\n- `destination_chain` is a chain name exactly as `GET /partner/send-out/routes` lists it (e.g. `Arbitrum One`, `BNB Smart Chain`, case-insensitive) or its `chain_id`\n- The order's own crypto is sent; only chains that carry that token are accepted\n- `destination_address` must be valid for the chain type (EVM `0x…`, Tron `T…`, Solana, TON)\n\n**Response includes:**\n- `forward_request` — pre-filled EIP-712 ForwardRequest object to sign\n- `eip712_domain` — domain parameters for EIP-712 signing\n- `quote_id` — bridge quote ID embedded in the transfer calldata\n- `to_amount` — estimated USDT amount to be received on the destination chain (atomic units)\n- `forwarder_nonce` — current on-chain nonce for your partner wallet\n","operationId":"getBridgeAuthorizationParameters","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}},{"name":"destination_chain","in":"query","required":true,"description":"Destination chain name as listed by `GET /partner/send-out/routes` (e.g. `Arbitrum One`), case-insensitive, or its `chain_id`","schema":{"type":"string"}},{"name":"destination_address","in":"query","required":true,"description":"Recipient address on the destination chain, in that chain's format","schema":{"type":"string"}}],"responses":{"200":{"description":"Authorization parameters returned successfully","content":{"application/json":{}}},"400":{"description":"`INVALID_REQUEST` — invalid destination_chain or destination_address, or a destination the chain cannot pay (`error.details.reason`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"Order is not in `completed` status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"- `WALLET_TYPE_MISMATCH` — the order belongs to an `external_wallet` customer.\n- `AMOUNT_TOO_LOW` — the order amount is too small to bridge to that chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Authorize send-out (cross-chain transfer)

> Submit the signed EIP-712 ForwardRequest to initiate a cross-chain send-out.\
> Unigox recovers the signer before relaying: a signature not made by \`from\`, a \`deadline\` in the\
> past, or a \`nonce\` that is not your current forwarder nonce is refused with \`400 INVALID\_REQUEST\`,\
> and nothing is relayed.\
> \
> Call \`GET bridge-authorization-parameters\` first to get the parameters to sign.\
> \
> After submission the order transitions to \`send\_out\_pending\`. Unigox\
> monitors the bridge transfer and updates the status to \`send\_out\_completed\` or\
> \`send\_out\_failed\` when the transfer settles. The partner receives a webhook for\
> each transition.\
> \
> When the send-out completes, the \`send\_out\_tx\_hash\` field in \`GET /orders/:id\`\
> contains the destination-chain transaction hash.\
> \
> \*\*This endpoint is idempotent at the on-chain level\*\* — the EIP-712 nonce prevents\
> duplicate submissions. A second call with the same nonce will be rejected.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"On-Ramp","description":"On-ramp operations (fiat to crypto) — partner initiates a buy order, vendor provides liquidity, end-user sends fiat"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/authorize-bridge":{"post":{"tags":["On-Ramp"],"summary":"Authorize send-out (cross-chain transfer)","description":"Submit the signed EIP-712 ForwardRequest to initiate a cross-chain send-out.\nUnigox recovers the signer before relaying: a signature not made by `from`, a `deadline` in the\npast, or a `nonce` that is not your current forwarder nonce is refused with `400 INVALID_REQUEST`,\nand nothing is relayed.\n\nCall `GET bridge-authorization-parameters` first to get the parameters to sign.\n\nAfter submission the order transitions to `send_out_pending`. Unigox\nmonitors the bridge transfer and updates the status to `send_out_completed` or\n`send_out_failed` when the transfer settles. The partner receives a webhook for\neach transition.\n\nWhen the send-out completes, the `send_out_tx_hash` field in `GET /orders/:id`\ncontains the destination-chain transaction hash.\n\n**This endpoint is idempotent at the on-chain level** — the EIP-712 nonce prevents\nduplicate submissions. A second call with the same nonce will be rejected.\n","operationId":"authorizeBridge","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destination_chain","destination_address","forward_request","signature"],"properties":{"destination_chain":{"type":"string","description":"Destination chain name as listed by `GET /partner/send-out/routes` (or its `chain_id`); must match the value used in bridge-authorization-parameters"},"destination_address":{"type":"string","description":"Recipient address on the destination chain, in that chain's format"},"forward_request":{"type":"object","description":"EIP-712 ForwardRequest object (values from bridge-authorization-parameters)","required":["from","to","value","gas","nonce","deadline","data"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string"},"gas":{"type":"string"},"nonce":{"type":"string"},"deadline":{"type":"string"},"data":{"type":"string"}}},"signature":{"type":"string","description":"EIP-712 signature of the ForwardRequest (hex, with 0x prefix)"}}}}}},"responses":{"200":{"description":"Send-out submitted successfully","content":{"application/json":{}}},"400":{"description":"Invalid request — bad forward_request, nonce mismatch, or invalid destination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"Order is not in `completed` status or send-out already in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`WALLET_TYPE_MISMATCH` — the order belongs to an `external_wallet` customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"502":{"description":"Transactor service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```
