Skip to main content
POST
/
v1
/
sender
/
orders
{
  "network": "starknet",
  "token": "USDC",
  "amount": "100.00",
  "rate": "1",
  "returnAddress": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
  "recipient": {
    "currency": "NGN",
    "institution": "GTBINGLA",
    "accountIdentifier": "0123456789",
    "accountName": "Jane Doe",
    "memo": "Invoice payment"
  }
}

{
  "status": "success",
  "message": "Order ready — approve the Gateway and submit createOrder from your wallet, then POST the orderId to orders/:id/submitted",
  "data": {
    "orderRef": "c162cba7-f1b1-48aa-9f80-6f803f50e155",
    "params": {
      "network": "starknet",
      "chainType": "starknet",
      "chainId": 23448594291968334,
      "chainIdHex": "0x534e5f4d41494e",
      "gatewayAddress": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
      "token": "0x33068f6539f8e6e6b131e6b2b814e6c34a5224bc66947c47dab9dfee93b35fb",
      "tokenSymbol": "USDC",
      "decimals": 6,
      "amount": "100000000",
      "approveAmount": "100000000",
      "rate": "137800",
      "senderFeeRecipient": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
      "senderFee": "0",
      "refundAddress": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
      "messageHash": "EbJcMEaq9nT+uCGBZyJ2fA9gKrvo...",
      "currency": "NGN",
      "providerIds": ["etoMCRIY"]
    }
  }
}
Create Order is a single endpoint — POST /v1/sender/orders. Rails dispatches on the network you pass:
  • Sui — custodial. Rails returns a deposit address / PTB (see Create Order).
  • EVM & Starknet — non-custodial (this page). Rails never takes custody, holds keys, or pays gas. It assembles the exact createOrder parameters your wallet needs — the Gateway address, live rate, token, amount, and the encrypted recipient blob — and records the order for status tracking.
Your wallet then approve()s the Gateway and calls createOrder(...) with the returned params. After submitting, report the on-chain orderId back via Submit On-chain Order; Rails polls the settlement aggregator and webhooks you on every status change.
The rate returned is a live LP quote — a snapshot. Submit promptly. An order created above the LP’s ceiling rate times out and auto-refunds to the order creator (returnAddress).
Fees & approval. The Gateway pulls amount + senderFee, so approve approveAmount (returned below), not just amount. Your fee (senderFee) is paid on-chain to feeAddress. This is separate from the protocol fee, which the aggregator charges automatically on-chain — you do not set it.

​
Header Parameters

​
API-Key
string
required
Unique API key issued manually through Telegram.

​
Request Body

​
network
string
required
The settlement chain identifier. EVM: ethereum, base, polygon, arbitrum-one, bnb-smart-chain, celo, lisk, scroll. Non-EVM: starknet.
​
token
string
required
The stablecoin symbol to send (USDC, USDT, and CNGN on some chains). Must be enabled on the selected network.
​
amount
string
required
The token amount to convert, in human units (e.g. "100.00").
​
rateId
string
A locked quote id from Get Rate. Preferred over a raw rate. (For EVM/Starknet the live LP rate is also re-quoted server-side at settlement.)
​
rate
string
A raw rate — used only when rateId is omitted.
​
returnAddress
string
required
The wallet of the order creator — the wallet that will call createOrder. Refunds return here, and it is the default sender-fee recipient. Must match the chain’s address format (EVM 20-byte hex, or a Starknet felt).
​
feeMode
string
How to compute your (the integrator’s) fee: percent (default) or fixed.
​
feePercent
string
Used when feeMode is percent — your fee as a percentage of the order amount (e.g. 1.5 = 1.5%).
​
feeAmount
string
Used when feeMode is fixed — a flat fee in the order’s token (e.g. 2 = 2 USDC). Must be less than amount.
​
feeAddress
string
The address that receives your fee on-chain (the Gateway’s senderFeeRecipient). Required whenever a fee is set. Same address format as the chain.
​
recipientId
string
A staged beneficiary id from Create Recipient. Preferred over an inline recipient.
​
recipient
object
Payout beneficiary details — used only when recipientId is omitted.
​
currency
string
required
Destination fiat ISO code (NGN, KES, …).
​
institution
string
required
Payout institution code from /v1/institutions/{currency_code}.
​
accountIdentifier
string
required
Payout account number / wallet handle.
​
accountName
string
required
Exact account name of record.
​
memo
string
required
Bank transfer memo.
​
providerId
string
Optional preferred LP provider id.

​
Response

​
status
string
Response state (success).
​
message
string
Human-readable message.
​
data
object
​
orderRef
string
Rails order id (UUID). Use it in the submit callback and status lookups.
​
params
object
The unsigned createOrder arguments. All integers are decimal strings (uint256 amount, uint96/u128 rate).
​
network
string
Chain identifier.
​
chainType
string
evm or starknet.
​
chainId
number
Chain id (EVM decimal id, or the Starknet SN_MAIN felt).
​
chainIdHex
string
Chain id in 0x hex.
​
gatewayAddress
string
Gateway proxy — the approve() + createOrder() target.
​
token
string
Token contract to send.
​
tokenSymbol
string
Token symbol.
​
decimals
number
Token decimals.
​
amount
string
Order amount in token subunits.
​
approveAmount
string
amount + senderFee in token subunits. Approve this on the token before calling createOrder — the Gateway pulls amount + senderFee.
​
rate
string
Rate as fixed-point (fiat-per-token × 100).
​
senderFeeRecipient
string
Fee recipient address.
​
senderFee
string
Sender fee in token subunits.
​
refundAddress
string
Refund target — equals returnAddress.
​
messageHash
string
Base64 RSA-encrypted recipient blob (the Gateway messageHash argument).
​
currency
string
Destination fiat code.
​
providerIds
array
Eligible LP provider ids.

​
Example Payloads

{
  "network": "starknet",
  "token": "USDC",
  "amount": "100.00",
  "rate": "1",
  "returnAddress": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
  "recipient": {
    "currency": "NGN",
    "institution": "GTBINGLA",
    "accountIdentifier": "0123456789",
    "accountName": "Jane Doe",
    "memo": "Invoice payment"
  }
}

{
  "status": "success",
  "message": "Order ready — approve the Gateway and submit createOrder from your wallet, then POST the orderId to orders/:id/submitted",
  "data": {
    "orderRef": "c162cba7-f1b1-48aa-9f80-6f803f50e155",
    "params": {
      "network": "starknet",
      "chainType": "starknet",
      "chainId": 23448594291968334,
      "chainIdHex": "0x534e5f4d41494e",
      "gatewayAddress": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
      "token": "0x33068f6539f8e6e6b131e6b2b814e6c34a5224bc66947c47dab9dfee93b35fb",
      "tokenSymbol": "USDC",
      "decimals": 6,
      "amount": "100000000",
      "approveAmount": "100000000",
      "rate": "137800",
      "senderFeeRecipient": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
      "senderFee": "0",
      "refundAddress": "0x06ff3a3b1532da65594fc98f9ca7200af6c3dbaf37e7339b0ebd3b3f2390c583",
      "messageHash": "EbJcMEaq9nT+uCGBZyJ2fA9gKrvo...",
      "currency": "NGN",
      "providerIds": ["etoMCRIY"]
    }
  }
}