Ctrlk
SDKsPostman Collection↺ Changelog
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
/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 (which still requires an API key).

Authentication: None. This is a public endpoint — no API key required (same as /partner/liquidity).

Body
anyOptional
or
anyOptional
Responses
200

Estimate retrieved successfully

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
post/api/v1/partner/onramp/estimate
POST /api/v1/partner/onramp/estimate HTTP/1.1
Host: api-staging.unigox.com
Content-Type: application/json
Accept: */*
Content-Length: 206

{
  "crypto_currency": "USDT",
  "fiat_currency": "VND",
  "fiat_amount": "26345",
  "payment_method_slug": "zalopay",
  "payment_network_slug": "napas-vietnam",
  "country_code": "VN",
  "provider_scope": "all",
  "partner_fee_pct": "1"
}
{
  "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.010000",
      "partner_fee_pct": 1,
      "total_fee": "0.015000"
    },
    "payment_method_slug": "zalopay",
    "payment_network_slug": "napas-vietnam",
    "provider_scope": "all",
    "is_indicative": true
  }
}

Get on-ramp quote

post
/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 (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). 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.

Authorizations
X-API-KeystringRequired

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

Body
anyOptional
or
anyOptional
Responses
200

Quote retrieved successfully

application/json
successbooleanRequired

Indicates if the request was successful

Example: true
post/api/v1/partner/onramp/quote
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: 234

{
  "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",
  "partner_fee_pct": "1"
}
{
  "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.010000",
      "partner_fee_pct": 1,
      "total_fee": "0.015000"
    },
    "payment_method_slug": "zalopay",
    "payment_network_slug": "napas-vietnam",
    "expires_at": "2026-03-30T19:15:50Z"
  }
}

Initiate on-ramp order

post
/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.

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.

Authorizations
X-API-KeystringRequired

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

Body
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
successbooleanRequired

Indicates if the request was successful

Example: true
post/api/v1/partner/onramp/initiate
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.005000",
      "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.010000",
      "partner_fee_pct": 1,
      "total_fee": "0.015000"
    },
    "timeline": [],
    "created_at": "2026-03-30T19:00:05Z"
  }
}

Submit payer details

post
/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
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

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
post/api/v1/partner/orders/{order_id}/submit-payer-details
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
}
{
  "success": true,
  "data": {
    "message": "payer details submitted successfully"
  }
}

Confirm fiat payment sent

post
/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
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
post/api/v1/partner/orders/{order_id}/confirm-payment-sent
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
/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
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
get/api/v1/partner/orders/{order_id}/bridge-authorization-parameters
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
/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
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
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
post/api/v1/partner/orders/{order_id}/authorize-bridge
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"
  }
}
PreviousUser Management
NextLiquidity

Last updated