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 should do next (e.g., authorize_crypto_transfer). The allowed_actions array lists all API actions available for the current status (e.g., ["authorize-crypto-transfer", "cancel"]). Each entry corresponds to a POST /api/v1/partner/orders/{order_id}/{action} endpoint.

Status mapping: Internal trade statuses are mapped to simplified partner-facing statuses. See the PartnerOrderStatus enum for all possible values.

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

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": "0.00",
      "partner_fee_pct": 0,
      "total_fee": "1.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

401

Unauthorized

404

Order not found

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 fiat payment has been received by the user for an off-ramp order. This triggers the crypto release from escrow to the buyer.

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

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": "0.00",
          "partner_fee_pct": 0,
          "total_fee": "1.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
    }
  }
}