Orders

Order management, status tracking, and lifecycle actions

Order details

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/orders/{order_id}

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 the recipient receives the fiat. When the order's has_fiat_settlement_notification is true (see the quote/order response), the order moves to completed on its own and you receive the status=completed webhook — no manual confirm needed. 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. See the Webhooks page → "Settlement notifications" for details.

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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

order_idstring · uuidRequired

Order UUID returned by the initiate endpoint

Example: b2c3d4e5-f6a7-8901-bcde-f12345678901

Responses

200

Order retrieved successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized — invalid or missing API key

application/json

404

Order not found or does not belong to this partner

application/json

500

Internal server error

application/json

get/api/v1/partner/orders/{order_id}

HTTPcURLJavaScriptPython

GET /api/v1/partner/orders/{order_id} HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "awaiting_crypto_transfer_authorization",
    "next_action": "authorize_crypto_transfer",
    "allowed_actions": [
      "authorize-crypto-transfer",
      "cancel"
    ],
    "crypto_transfer_authorization_seconds_left": 1720,
    "amounts": {
      "crypto_amount": "101.50",
      "fiat_amount": "152880.00",
      "crypto_currency": "USDT",
      "fiat_currency": "NGN",
      "rate": "1530.12"
    },
    "fee_breakdown": {
      "platform_fee": "1.50",
      "platform_fee_pct": 1.5,
      "partner_fee": "1.00",
      "partner_fee_pct": 1,
      "total_fee": "2.50"
    },
    "timeline": [
      {
        "status": "created",
        "timestamp": "2026-02-01T12:00:05Z",
        "description": "Order created"
      },
      {
        "status": "awaiting_crypto_transfer_authorization",
        "timestamp": "2026-02-01T12:00:06Z",
        "description": "Awaiting crypto transfer authorization"
      }
    ],
    "created_at": "2026-02-01T12:00:05Z",
    "updated_at": "2026-02-01T12:00:06Z"
  }
}

Get transfer authorization parameters

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/orders/{order_id}/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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

order_idstring · uuidRequired

Order UUID

Responses

200

Transfer authorization parameters returned

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized

404

No order with this id belongs to your partner account.

409

The order exists but is not at a stage where it can be funded. A new order starts at awaiting_liquidity_provider with no escrow yet, so this is the normal answer until a provider accepts — poll GET /orders/{order_id} until next_action becomes authorize_crypto_transfer.

application/json

get/api/v1/partner/orders/{order_id}/transfer-authorization-parameters

HTTPcURLJavaScriptPython

GET /api/v1/partner/orders/{order_id}/transfer-authorization-parameters HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "order_id": "123e4567-e89b-12d3-a456-426614174000",
    "network_preset": "text",
    "chain_id": "text",
    "rpc_url": "text",
    "token_address": "text",
    "forwarder_address": "text",
    "recipient_address": "text",
    "sender_address": "text",
    "amount_atomic": "text",
    "amount_human": "text",
    "crypto_currency": "text",
    "crypto_decimals": 1,
    "recommended_gas_limit": "text",
    "recommended_ttl_seconds": 1,
    "transfer_data": "text",
    "forwarder_nonce": "text",
    "authorization_path": "text"
  }
}

Authorize crypto transfer

post

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/orders/{order_id}/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: https://github.com/Unigox/sdk_python/blob/main/partner_authorize_crypto_transfer_sdk.py

• JavaScript: https://github.com/Unigox/sdk_javascript/blob/main/partner_authorize_crypto_transfer_sdk.js

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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

order_idstring · uuidRequired

Order UUID

Example: b2c3d4e5-f6a7-8901-bcde-f12345678901

Body

application/json

forward_requestobjectRequired

Signed EIP-712 ForwardRequest payload

signaturestringRequired

Hex-encoded signature from partner wallet

Responses

200

Crypto authorization accepted

No content

400

Bad Request

401

Unauthorized

404

Order not found

409

Order is not in the correct status for crypto authorization

422

Insufficient token balance — the partner wallet does not hold enough tokens to fund the escrow. Top up the wallet and retry.

application/json

502

Transactor service error (e.g. on-chain simulation failed)

post/api/v1/partner/orders/{order_id}/authorize-crypto-transfer

HTTPcURLJavaScriptPython

POST /api/v1/partner/orders/{order_id}/authorize-crypto-transfer HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 259

{
  "forward_request": {
    "from": "0x674b16054290b4f06D7Ba8e3Ac379E3B0a359a16",
    "to": "0x2222222222222222222222222222222222222222",
    "value": "0",
    "gas": "500000",
    "nonce": "0",
    "deadline": "1760000000",
    "data": "0xa9059cbb000000000000000000000000..."
  },
  "signature": "0xabc123..."
}

No content

Confirm fiat received

post

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/orders/{order_id}/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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

order_idstring · uuidRequired

Order UUID

Example: b2c3d4e5-f6a7-8901-bcde-f12345678901

Responses

200

Fiat receipt confirmed successfully

No content

400

Bad Request

401

Unauthorized

404

Order not found

post/api/v1/partner/orders/{order_id}/confirm-fiat-received

HTTPcURLJavaScriptPython

POST /api/v1/partner/orders/{order_id}/confirm-fiat-received HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Cancel order

post

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/orders/{order_id}/cancel

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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

order_idstring · uuidRequired

Order UUID

Example: b2c3d4e5-f6a7-8901-bcde-f12345678901

Responses

200

Order cancelled successfully

No content

400

Bad Request — cancellation not allowed at current status

401

Unauthorized

404

Order not found

post/api/v1/partner/orders/{order_id}/cancel

HTTPcURLJavaScriptPython

POST /api/v1/partner/orders/{order_id}/cancel HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

No content

List orders

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/orders

Get a paginated list of orders with optional filtering by status. Each order includes allowed_actions indicating which API actions are available.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Query parameters

statusstring · enumOptional

Filter by partner order status

Example: completedPossible values:

pageintegerOptional

Page number (default 1)

Default: 1Example: 1

limitinteger · max: 100Optional

Results per page (default 20, max 100)

Default: 20Example: 20

Responses

200

Orders retrieved successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized — invalid or missing API key

application/json

get/api/v1/partner/orders

HTTPcURLJavaScriptPython

GET /api/v1/partner/orders HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "orders": [
      {
        "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "status": "completed",
        "next_action": null,
        "allowed_actions": [],
        "amounts": {
          "crypto_amount": "101.50",
          "fiat_amount": "152880.00",
          "crypto_currency": "USDT",
          "fiat_currency": "NGN",
          "rate": "1530.12"
        },
        "fee_breakdown": {
          "platform_fee": "1.50",
          "platform_fee_pct": 1.5,
          "partner_fee": "1.00",
          "partner_fee_pct": 1,
          "total_fee": "2.50"
        },
        "timeline": [
          {
            "status": "created",
            "timestamp": "2026-02-01T12:00:05Z",
            "description": "Order created"
          },
          {
            "status": "completed",
            "timestamp": "2026-02-01T12:30:00Z",
            "description": "Order completed"
          }
        ],
        "created_at": "2026-02-01T12:00:05Z",
        "updated_at": "2026-02-01T12:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total_count": 42,
      "total_pages": 3
    }
  }
}