# Orders
Order management, status tracking, and lifecycle actions
## Order details
> Get the current status, amounts, and full timeline for a specific order.\
> The \`next\_action\` field indicates what the partner \*\*must\*\* do to advance the order.\
> \`null\` means no action is required from the partner at this stage — the order is waiting\
> for the counterparty (e.g. the buyer to submit fiat payment proof).\
> \
> The \`allowed\_actions\` array lists all API actions the partner \*\*can\*\* perform at the current\
> status. An action can be in \`allowed\_actions\` even when \`next\_action\` is \`null\` — this means\
> the action is optional. For example, \`confirm-fiat-received\` is available at \`crypto\_received\`\
> as a fast-track: if you already know the fiat has arrived (via your own systems), you can\
> confirm immediately without waiting for the buyer's payment proof flow to complete.\
> \
> \*\*Order flow summary:\*\*\
> \
> \| Status | next\_action | Who acts |\
> \|---|---|---|\
> \| \`created\` | — | Partner (or wait for vendor match) |\
> \| \`awaiting\_crypto\_transfer\_authorization\` | \`authorize\_crypto\_transfer\` | \*\*Partner\*\* |\
> \| \`crypto\_transfer\_authorization\_pending\` | — | System (on-chain confirmation) |\
> \| \`crypto\_received\` | — | \*\*Buyer\*\* submits fiat payment proof |\
> \| \`fiat\_payment\_started\` | — | System reviews proof |\
> \| \`fiat\_payment\_review\_started\` | — | System accepts/rejects proof |\
> \| \`awaiting\_fiat\_received\_confirmation\` | \`confirm\_fiat\_received\` | \*\*Partner\*\* |\
> \| \`completed\` | — | — |\
> \
> \*\*Fiat settlement and confirmation:\*\*\
> \
> You can call \`confirm-fiat-received\` at any time after crypto is in escrow.\
> You do not need to wait for a system notification. If you know through your\
> own systems that the recipient has received the fiat payment, confirm immediately.\
> \
> Some liquidity providers also send automatic settlement confirmations. When this\
> happens, the order moves to \`completed\` on its own. If you already confirmed\
> manually, the auto-confirmation is a no-op. If the auto-confirmation arrives\
> first, your manual confirm call is also a no-op. Both paths are safe.\
> \
> \*\*How to implement:\*\*\
> \- Always implement a \`confirm-fiat-received\` call in your flow.\
> \- Listen for webhooks. If you receive \`status=completed\`, no further action needed.\
> \- If \`next\_action=confirm\_fiat\_received\`, call \`confirm-fiat-received\` when you\
> know fiat has been received.\
> \- Do not wait for \`next\_action\` if you already have confirmation from your\
> own banking or payment systems.\
> \
> \*\*Possible statuses:\*\* \`created\`, \`awaiting\_liquidity\_provider\`, \`awaiting\_crypto\_transfer\_authorization\`, \`crypto\_transfer\_authorization\_pending\`, \`crypto\_received\`, \`fiat\_payment\_started\`, \`awaiting\_fiat\_received\_confirmation\`, \`fiat\_received\_confirmed\`, \`crypto\_release\_pending\`, \`completed\`, \`cancelled\`, \`failed\`, \`price\_changed\_requote\_needed\`.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"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","nullable":true,"description":"The action the partner **must** perform to advance the order. `null` means\nno action is required from the partner at this stage — the order is waiting\nfor the counterparty or for an automated system step.\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- `null` — no required action (waiting for buyer or system)\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address",null]},"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 `null` — 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` → `[\"cancel\"]`\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`, `cancelled`, `failed` → `[]`\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.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","nullable":true,"description":"Order type. Present for on-ramp orders. Absent for off-ramp orders.\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"}}},"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- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\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, partner must confirm payment sent\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","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","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units)"},"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":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}},"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"}}},"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\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate\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\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` — on-chain transaction relay failed (e.g. simulation reverted)\n- `INSUFFICIENT_BALANCE` — partner wallet lacks tokens to fund escrow\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n","enum":["QUOTE_EXPIRED","QUOTE_NOT_FOUND","QUOTE_ALREADY_USED","PRICE_CHANGED_REQUOTE","ORDER_NOT_FOUND","NO_OFFERS_AVAILABLE","INVALID_REQUEST","INVALID_PAYMENT_DETAILS","RAIL_ROUTE_MISMATCH","UNAUTHORIZED","INTERNAL_ERROR","INVALID_STATUS","TRANSACTOR_ERROR","INSUFFICIENT_BALANCE","OPERATION_NOT_ALLOWED"]},"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}":{"get":{"tags":["Orders"],"summary":"Order details","description":"Get the current status, amounts, and full timeline for a specific order.\nThe `next_action` field indicates what the partner **must** do to advance the order.\n`null` means no action is required from the partner at this stage — the order is waiting\nfor the counterparty (e.g. the buyer to submit fiat payment proof).\n\nThe `allowed_actions` array lists all API actions the partner **can** perform at the current\nstatus. An action can be in `allowed_actions` even when `next_action` is `null` — this means\nthe action is optional. For example, `confirm-fiat-received` is available at `crypto_received`\nas a fast-track: if you already know the fiat has arrived (via your own systems), you can\nconfirm immediately without waiting for the buyer's payment proof flow to complete.\n\n**Order flow summary:**\n\n| Status | next_action | Who acts |\n|---|---|---|\n| `created` | — | Partner (or wait for vendor match) |\n| `awaiting_crypto_transfer_authorization` | `authorize_crypto_transfer` | **Partner** |\n| `crypto_transfer_authorization_pending` | — | System (on-chain confirmation) |\n| `crypto_received` | — | **Buyer** submits fiat payment proof |\n| `fiat_payment_started` | — | System reviews proof |\n| `fiat_payment_review_started` | — | System accepts/rejects proof |\n| `awaiting_fiat_received_confirmation` | `confirm_fiat_received` | **Partner** |\n| `completed` | — | — |\n\n**Fiat settlement and confirmation:**\n\nYou can call `confirm-fiat-received` at any time after crypto is in escrow.\nYou do not need to wait for a system notification. If you know through your\nown systems that the recipient has received the fiat payment, confirm immediately.\n\nSome liquidity providers also send automatic settlement confirmations. When this\nhappens, the order moves to `completed` on its own. If you already confirmed\nmanually, the auto-confirmation is a no-op. If the auto-confirmation arrives\nfirst, your manual confirm call is also a no-op. Both paths are safe.\n\n**How to implement:**\n- Always implement a `confirm-fiat-received` call in your flow.\n- Listen for webhooks. If you receive `status=completed`, no further action needed.\n- If `next_action=confirm_fiat_received`, call `confirm-fiat-received` when you\n know fiat has been received.\n- Do not wait for `next_action` if you already have confirmation from your\n own banking or payment systems.\n\n**Possible statuses:** `created`, `awaiting_liquidity_provider`, `awaiting_crypto_transfer_authorization`, `crypto_transfer_authorization_pending`, `crypto_received`, `fiat_payment_started`, `awaiting_fiat_received_confirmation`, `fiat_received_confirmed`, `crypto_release_pending`, `completed`, `cancelled`, `failed`, `price_changed_requote_needed`.\n","operationId":"getOrder","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID returned by the initiate endpoint","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerOrderResponse"}}}]}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found or does not belong to this partner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```
## Get transfer authorization parameters
> Returns pre-filled parameters required to build and sign the EIP-712 forward request.\
> Use this endpoint first, then sign locally and send the signature to\
> \`/api/v1/partner/orders/{order\_id}/authorize-crypto-transfer\`.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"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"}}}}},"paths":{"/api/v1/partner/orders/{order_id}/transfer-authorization-parameters":{"get":{"tags":["SDK","Orders"],"summary":"Get transfer authorization parameters","description":"Returns pre-filled parameters required to build and sign the EIP-712 forward request.\nUse this endpoint first, then sign locally and send the signature to\n`/api/v1/partner/orders/{order_id}/authorize-crypto-transfer`.\n","operationId":"getTransferAuthorizationParameters","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transfer authorization parameters returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"network_preset":{"type":"string"},"chain_id":{"type":"string"},"rpc_url":{"type":"string","description":"JSON-RPC URL for the target chain"},"token_address":{"type":"string"},"forwarder_address":{"type":"string"},"recipient_address":{"type":"string","description":"Escrow address to receive the crypto"},"sender_address":{"type":"string","description":"Partner wallet address (must match the signing private key)"},"amount_atomic":{"type":"string"},"amount_human":{"type":"string"},"crypto_currency":{"type":"string"},"crypto_decimals":{"type":"integer"},"recommended_gas_limit":{"type":"string"},"recommended_ttl_seconds":{"type":"integer"},"transfer_data":{"type":"string","description":"Pre-encoded ERC20 transfer(address,uint256) calldata (hex with 0x prefix)"},"forwarder_nonce":{"type":"string","description":"Current forwarder nonce for the sender address (used in EIP-712 signing)"},"authorization_path":{"type":"string"}}}}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"}}}}}}
```
## Authorize crypto transfer
> Submit signed EIP-712 \`forward\_request\` to authorize transfer of order crypto to escrow.\
> \
> \*\*Security note:\*\* Your private key is never sent to the API. The SDK uses it locally to\
> construct and sign the EIP-712 ForwardRequest on your machine. Only the resulting signature\
> and the unsigned forward\_request fields are submitted. You can verify this by reading the\
> SDK source code.\
> \
> Recommended: use SDK helper files (only 4 arguments needed):\
> \- Python: \`
> \- JavaScript: \`
> \
> The SDK automatically fetches all required parameters (chain, token, forwarder, escrow\
> address, RPC URL) from the \`transfer-authorization-parameters\` endpoint.\
> \
> SDK helper options:\
> \- End-to-end one call: \`authorize\_crypto\_transfer(...)\` / \`authorizeCryptoTransfer(...)\`\
> \- Build unsigned request only: \`build\_forward\_request(...)\` / \`buildForwardRequest(...)\`\
> \- Sign existing request only: \`sign\_forward\_request(...)\` / \`signForwardRequest(...)\`\
> \- Build full request body \`{forward\_request, signature}\`:\
> \`build\_authorize\_crypto\_transfer\_payload(...)\` / \`buildAuthorizeCryptoTransferPayload(...)\`\
> \
> Manual implementation: call \`GET /transfer-authorization-parameters\` first, then build\
> the EIP-712 typed data and sign with your partner wallet private key locally.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"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\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate\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\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` — on-chain transaction relay failed (e.g. simulation reverted)\n- `INSUFFICIENT_BALANCE` — partner wallet lacks tokens to fund escrow\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n","enum":["QUOTE_EXPIRED","QUOTE_NOT_FOUND","QUOTE_ALREADY_USED","PRICE_CHANGED_REQUOTE","ORDER_NOT_FOUND","NO_OFFERS_AVAILABLE","INVALID_REQUEST","INVALID_PAYMENT_DETAILS","RAIL_ROUTE_MISMATCH","UNAUTHORIZED","INTERNAL_ERROR","INVALID_STATUS","TRANSACTOR_ERROR","INSUFFICIENT_BALANCE","OPERATION_NOT_ALLOWED"]},"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-crypto-transfer":{"post":{"tags":["SDK","Orders"],"summary":"Authorize crypto transfer","description":"Submit signed EIP-712 `forward_request` to authorize transfer of order crypto to escrow.\n\n**Security note:** Your private key is never sent to the API. The SDK uses it locally to\nconstruct and sign the EIP-712 ForwardRequest on your machine. Only the resulting signature\nand the unsigned forward_request fields are submitted. You can verify this by reading the\nSDK source code.\n\nRecommended: use SDK helper files (only 4 arguments needed):\n- Python: `https://github.com/Unigox/sdk_python/blob/main/partner_authorize_crypto_transfer_sdk.py`\n- JavaScript: `https://github.com/Unigox/sdk_javascript/blob/main/partner_authorize_crypto_transfer_sdk.js`\n\nThe SDK automatically fetches all required parameters (chain, token, forwarder, escrow\naddress, RPC URL) from the `transfer-authorization-parameters` endpoint.\n\nSDK helper options:\n- End-to-end one call: `authorize_crypto_transfer(...)` / `authorizeCryptoTransfer(...)`\n- Build unsigned request only: `build_forward_request(...)` / `buildForwardRequest(...)`\n- Sign existing request only: `sign_forward_request(...)` / `signForwardRequest(...)`\n- Build full request body `{forward_request, signature}`:\n `build_authorize_crypto_transfer_payload(...)` / `buildAuthorizeCryptoTransferPayload(...)`\n\nManual implementation: call `GET /transfer-authorization-parameters` first, then build\nthe EIP-712 typed data and sign with your partner wallet private key locally.\n","operationId":"authorizeCryptoTransfer","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":["forward_request","signature"],"properties":{"forward_request":{"type":"object","description":"Signed EIP-712 ForwardRequest payload"},"signature":{"type":"string","description":"Hex-encoded signature from partner wallet"}}}}}},"responses":{"200":{"description":"Crypto authorization accepted"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"},"409":{"description":"Order is not in the correct status for crypto authorization"},"422":{"description":"Insufficient token balance — the partner wallet does not hold enough\ntokens to fund the escrow. Top up the wallet and retry.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"502":{"description":"Transactor service error (e.g. on-chain simulation failed)"}}}}}}
```
## Confirm fiat received
> Confirm that the recipient has received the fiat payment for an off-ramp order.\
> This triggers the crypto release from escrow.\
> \
> Call this endpoint as soon as you know fiat has been received. You do not need\
> to wait for a system prompt. If you have confirmation from your own banking or\
> payment systems, confirm immediately.\
> \
> This endpoint is idempotent. If the order already completed (via automatic\
> settlement confirmation from the liquidity provider), calling this returns\
> the current order status with no side effects.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"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."}}},"paths":{"/api/v1/partner/orders/{order_id}/confirm-fiat-received":{"post":{"tags":["Orders"],"summary":"Confirm fiat received","description":"Confirm that the recipient has received the fiat payment for an off-ramp order.\nThis triggers the crypto release from escrow.\n\nCall this endpoint as soon as you know fiat has been received. You do not need\nto wait for a system prompt. If you have confirmation from your own banking or\npayment systems, confirm immediately.\n\nThis endpoint is idempotent. If the order already completed (via automatic\nsettlement confirmation from the liquidity provider), calling this returns\nthe current order status with no side effects.\n","operationId":"confirmFiatReceived","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Fiat receipt confirmed successfully"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"}}}}}}
```
## Cancel order
> Cancel an order if cancellation is allowed at the current status.\
> Check \`allowed\_actions\` on the order response — \`cancel\` is available when cancellation is permitted.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"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."}}},"paths":{"/api/v1/partner/orders/{order_id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancel order","description":"Cancel an order if cancellation is allowed at the current status.\nCheck `allowed_actions` on the order response — `cancel` is available when cancellation is permitted.\n","operationId":"cancelOrder","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order cancelled successfully"},"400":{"description":"Bad Request — cancellation not allowed at current status"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"}}}}}}
```
## List orders
> Get a paginated list of orders with optional filtering by status.\
> Each order includes \`allowed\_actions\` indicating which API actions are available.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"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","nullable":true,"description":"The action the partner **must** perform to advance the order. `null` means\nno action is required from the partner at this stage — the order is waiting\nfor the counterparty or for an automated system step.\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- `null` — no required action (waiting for buyer or system)\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address",null]},"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 `null` — 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` → `[\"cancel\"]`\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`, `cancelled`, `failed` → `[]`\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.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","nullable":true,"description":"Order type. Present for on-ramp orders. Absent for off-ramp orders.\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"}}},"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- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\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, partner must confirm payment sent\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","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","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units)"},"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":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}},"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"}}},"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\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate\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\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` — on-chain transaction relay failed (e.g. simulation reverted)\n- `INSUFFICIENT_BALANCE` — partner wallet lacks tokens to fund escrow\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n","enum":["QUOTE_EXPIRED","QUOTE_NOT_FOUND","QUOTE_ALREADY_USED","PRICE_CHANGED_REQUOTE","ORDER_NOT_FOUND","NO_OFFERS_AVAILABLE","INVALID_REQUEST","INVALID_PAYMENT_DETAILS","RAIL_ROUTE_MISMATCH","UNAUTHORIZED","INTERNAL_ERROR","INVALID_STATUS","TRANSACTOR_ERROR","INSUFFICIENT_BALANCE","OPERATION_NOT_ALLOWED"]},"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":{"get":{"tags":["Orders"],"summary":"List orders","description":"Get a paginated list of orders with optional filtering by status.\nEach order includes `allowed_actions` indicating which API actions are available.\n","operationId":"listOrders","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by partner order status","schema":{"type":"string","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","completed","cancelled","failed","price_changed_requote_needed"]}},{"name":"page","in":"query","required":false,"description":"Page number (default 1)","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Results per page (default 20, max 100)","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Orders retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrderResponse"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}]}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developers.unigox.com/api-reference/orders.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.