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

post

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

/api/v1/partner/onramp/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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Body

application/json

anyOptional

or

anyOptional

Responses

200

Estimate retrieved successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Bad request — invalid parameters, missing required fields, unsupported cryptocurrency, or invalid provider_scope.

application/json

401

Unauthorized — missing or invalid API key

application/json

409

No offers available for the requested pair/amount

application/json

500

Internal Server Error

post

/api/v1/partner/onramp/estimate

HTTPcURLJavaScriptPython

POST /api/v1/partner/onramp/estimate HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 184

{
  "crypto_currency": "USDT",
  "fiat_currency": "VND",
  "fiat_amount": "26345",
  "payment_method_slug": "zalopay",
  "payment_network_slug": "napas-vietnam",
  "country_code": "VN",
  "provider_scope": "all"
}

{
  "success": true,
  "data": {
    "rate": "26345.00",
    "crypto_amount": "1.005000",
    "fiat_amount": "26345.00",
    "fee_breakdown": {
      "platform_fee": "0.005000",
      "platform_fee_pct": 0.5,
      "partner_fee": "0.00",
      "partner_fee_pct": 0,
      "total_fee": "0.005000"
    },
    "payment_method_slug": "zalopay",
    "payment_network_slug": "napas-vietnam",
    "provider_scope": "all",
    "is_indicative": true
  }
}

Get on-ramp quote

post

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

/api/v1/partner/onramp/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 (partner's markup, currently 0, configurable via dashboard in a future release), and total_fee (sum of both).

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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Body

application/json

anyOptional

or

anyOptional

Responses

200

Quote retrieved successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Bad request — invalid parameters or missing required fields

application/json

401

Unauthorized — invalid or missing API key

application/json

404

User not found

application/json

409

No offers available for the requested pair

application/json

500

Internal server error

application/json

post

/api/v1/partner/onramp/quote

HTTPcURLJavaScriptPython

POST /api/v1/partner/onramp/quote HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "user_uuid": "23d60610-9737-43b2-a751-a2c6a7bba457",
  "fiat_amount": "26345",
  "fiat_currency": "VND",
  "crypto_currency": "USDT",
  "payment_method_slug": "zalopay",
  "payment_network_slug": "napas-vietnam",
  "country_code": "VN"
}

{
  "success": true,
  "data": {
    "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "rate": "26345.00",
    "crypto_amount": "1.005000",
    "fiat_amount": "26345.00",
    "fee_breakdown": {
      "platform_fee": "0.005000",
      "platform_fee_pct": 0.5,
      "partner_fee": "0.00",
      "partner_fee_pct": 0,
      "total_fee": "0.005000"
    },
    "payment_method_slug": "zalopay",
    "payment_network_slug": "napas-vietnam",
    "expires_at": "2026-03-30T19:15:50Z"
  }
}

Initiate on-ramp order

post

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

/api/v1/partner/onramp/initiate

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.

At awaiting_fiat_transfer the partner must call confirm-payment-sent to advance the order. If the order type is payment_request, call submit-payer-details first before confirming.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Body

application/json

quote_idstring · uuidRequired

Quote ID from the quote endpoint. Payment details are taken from the quote.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

reference_idstringOptional

Optional partner-supplied external reference ID (e.g. your internal order ID). Stored on the order and echoed back in responses.

Example: your-internal-order-id

Responses

201

On-ramp order created successfully

application/json

400

Bad request — missing required fields

application/json

401

Unauthorized — invalid or missing API key

application/json

404

Quote not found

application/json

409

Quote expired or already used

application/json

500

Internal server error

application/json

post

/api/v1/partner/onramp/initiate

HTTPcURLJavaScriptPython

POST /api/v1/partner/onramp/initiate HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_id": "your-internal-order-id"
}

{
  "success": true,
  "data": {
    "order_id": "ce3cfd6a-1234-5678-abcd-ef1234567890",
    "status": "awaiting_liquidity_provider",
    "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference_id": "your-internal-order-id",
    "order_type": "onramp",
    "amounts": {
      "crypto_amount": "1.010025",
      "fiat_amount": "26476.72",
      "crypto_currency": "USDT",
      "fiat_currency": "VND",
      "rate": "26345.00"
    },
    "fee_breakdown": {
      "platform_fee": "0.005000",
      "platform_fee_pct": 0.5,
      "partner_fee": "0.00",
      "partner_fee_pct": 0,
      "total_fee": "0.005000"
    },
    "timeline": [],
    "created_at": "2026-03-30T19:00:05Z"
  }
}

Submit payer details

post

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

/api/v1/partner/orders/{order_id}/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. The partner receives vendor payment details in the vendor_payment_details field of GET /orders/:id 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. The end-user's account details must be submitted here first so the vendor knows where to send the request. 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.

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: ce3cfd6a-1234-5678-abcd-ef1234567890

Body

application/json

Submit the payer's payment details for a payment_request on-ramp order. Provide exactly one of payment_details_id (saved profile) or payment_details (inline object).

or

Responses

200

Payer details submitted successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Bad request — invalid or missing payer details

application/json

401

Unauthorized — invalid or missing API key

application/json

404

Order not found

application/json

409

Order is not in the correct status or not a payment_request order

application/json

500

Internal server error

application/json

post

/api/v1/partner/orders/{order_id}/submit-payer-details

HTTPcURLJavaScriptPython

POST /api/v1/partner/orders/{order_id}/submit-payer-details HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "payment_details_id": 1444
}

Using a saved payment profileProviding details inline

{
  "success": true,
  "data": {
    "message": "payer details submitted successfully"
  }
}

Confirm fiat payment sent

post

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

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

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

order_idstring · uuidRequired

Order UUID

Example: ce3cfd6a-1234-5678-abcd-ef1234567890

Responses

200

Payment confirmed successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Bad Request

application/json

401

Unauthorized — invalid or missing API key

application/json

404

Order not found

application/json

409

Order is not in awaiting_fiat_transfer status

application/json

500

Internal server error

application/json

post

/api/v1/partner/orders/{order_id}/confirm-payment-sent

HTTPcURLJavaScriptPython

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

{
  "success": true,
  "data": {
    "order_id": "ce3cfd6a-1234-5678-abcd-ef1234567890",
    "status": "fiat_transfer_pending"
  }
}

Get send-out authorization parameters

get

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

/api/v1/partner/orders/{order_id}/bridge-authorization-parameters

After an on-ramp order reaches completed status (crypto on master wallet), the partner can optionally initiate a cross-chain send-out to transfer the USDT to an external network (e.g. Arbitrum).

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 must be a supported chain slug (e.g. arbitrum, ethereum)

• destination_address must be a valid EVM address

Response includes:

• forward_request — pre-filled EIP-712 ForwardRequest object to sign

• eip712_domain — domain parameters for EIP-712 signing

• quote_id — Relay 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 the master wallet

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

order_idstring · uuidRequired

Order UUID

Example: ce3cfd6a-1234-5678-abcd-ef1234567890

Query parameters

destination_chainstringRequired

Destination chain slug (e.g. arbitrum, ethereum)

Example: arbitrum

destination_addressstringRequired

Recipient EVM address on the destination chain

Example: 0x9B61e9b3aed5bbFa66d778854E3dE7AF3241F021

Responses

200

Authorization parameters returned successfully

application/json

400

Invalid destination_chain or destination_address

application/json

401

Unauthorized — invalid or missing API key

application/json

404

Order not found

application/json

409

Order is not in completed status

application/json

500

Internal server error

application/json

get

/api/v1/partner/orders/{order_id}/bridge-authorization-parameters

HTTPcURLJavaScriptPython

GET /api/v1/partner/orders/{order_id}/bridge-authorization-parameters?destination_chain=text&destination_address=text HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "order_id": "ce3cfd6a-1234-5678-abcd-ef1234567890",
    "chain_id": "660279",
    "rpc_url": "https://xai-chain.net/rpc",
    "token_address": "0xf86Cc81F4E480CF54Eb013FFe6929a0C2Ad5EdCA",
    "forwarder_address": "0x6fFCF38bEc8c733b096958fcd2a8E31A00530EDC",
    "solver_address": "0x00A72adEB6542916F53dc2d78450CD436320868B",
    "sender_address": "0x6b14951552EA9fCE8f58EC52B909C14CB0619Af2",
    "amount_atomic": "10100",
    "amount_human": "0.010100",
    "crypto_currency": "USDT",
    "crypto_decimals": 6,
    "recommended_gas": "500000",
    "recommended_ttl": 3600,
    "transfer_data": "0xa9059cbb...",
    "forwarder_nonce": "63",
    "quote_id": "0x9b0539b1...",
    "to_amount": "10100",
    "destination_chain": "arbitrum",
    "destination_address": "0x9B61e9b3aed5bbFa66d778854E3dE7AF3241F021",
    "expires_at": "2026-04-03T17:13:12Z",
    "authorization_path": "/api/v1/partner/orders/ce3cfd6a-1234-5678-abcd-ef1234567890/authorize-bridge"
  }
}

Authorize send-out (cross-chain transfer)

post

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

/api/v1/partner/orders/{order_id}/authorize-bridge

Submit the signed EIP-712 ForwardRequest to initiate a cross-chain send-out. The signature is verified on-chain via the XAI forwarder contract.

Call GET bridge-authorization-parameters first to get the parameters to sign.

After submission the order transitions to send_out_pending. A background worker monitors the Relay bridge 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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

order_idstring · uuidRequired

Order UUID

Example: ce3cfd6a-1234-5678-abcd-ef1234567890

Body

application/json

destination_chainstringRequired

Destination chain slug (must match the value used in bridge-authorization-parameters)

Example: arbitrum

destination_addressstringRequired

Recipient EVM address on the destination chain

Example: 0x9B61e9b3aed5bbFa66d778854E3dE7AF3241F021

signaturestringRequired

EIP-712 signature of the ForwardRequest (hex, with 0x prefix)

Example: 0xc9a69a67...

Responses

200

Send-out submitted successfully

application/json

400

Invalid request — bad forward_request, nonce mismatch, or invalid destination

application/json

401

Unauthorized — invalid or missing API key

application/json

404

Order not found

application/json

409

Order is not in completed status or send-out already in progress

application/json

500

Internal server error

application/json

502

Transactor service unavailable

application/json

post

/api/v1/partner/orders/{order_id}/authorize-bridge

HTTPcURLJavaScriptPython

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

{
  "destination_chain": "arbitrum",
  "destination_address": "0x9B61e9b3aed5bbFa66d778854E3dE7AF3241F021",
  "forward_request": {
    "from": "0x6b14951552EA9fCE8f58EC52B909C14CB0619Af2",
    "to": "0xf86Cc81F4E480CF54Eb013FFe6929a0C2Ad5EdCA",
    "value": "0",
    "gas": "500000",
    "nonce": "63",
    "deadline": "1775236548",
    "data": "0xa9059cbb..."
  },
  "signature": "0xc9a69a67..."
}

{
  "success": true,
  "data": {
    "order_id": "ce3cfd6a-1234-5678-abcd-ef1234567890",
    "status": "send_out_pending"
  }
}