{
"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"]
}
}
}
API Reference
Create Order — EVM & Starknet
The unified create-order endpoint, non-custodial branch. When network is an EVM or Starknet chain, Rails returns the unsigned createOrder params and the client’s own wallet submits the transaction.
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
createOrderparameters your wallet needs — the Gateway address, live rate, token, amount, and the encrypted recipient blob — and records the order for status tracking.
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
string
required
Unique API key issued manually through Telegram.
Request Body
string
required
The settlement chain identifier. EVM:
ethereum, base, polygon,
arbitrum-one, bnb-smart-chain, celo, lisk, scroll. Non-EVM:
starknet.string
required
The stablecoin symbol to send (
USDC, USDT, and CNGN on some chains).
Must be enabled on the selected network.string
required
The token amount to convert, in human units (e.g.
"100.00").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.)string
A raw rate — used only when
rateId is omitted.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).string
How to compute your (the integrator’s) fee:
percent (default) or fixed.string
Used when
feeMode is percent — your fee as a percentage of the order
amount (e.g. 1.5 = 1.5%).string
Used when
feeMode is fixed — a flat fee in the order’s token (e.g.
2 = 2 USDC). Must be less than amount.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.string
A staged beneficiary id from
Create Recipient. Preferred over
an inline
recipient.object
Payout beneficiary details — used only when
recipientId is omitted.
string
required
Destination fiat ISO code (
NGN, KES, …).string
required
Payout institution code from
/v1/institutions/{currency_code}.string
required
Payout account number / wallet handle.
string
required
Exact account name of record.
string
required
Bank transfer memo.
string
Optional preferred LP provider id.
Response
string
Response state (
success).string
Human-readable message.
object
string
Rails order id (UUID). Use it in the submit callback and status lookups.
object
The unsigned
createOrder arguments. All integers are decimal strings
(uint256 amount, uint96/u128 rate).
string
Chain identifier.
string
evm or starknet.number
Chain id (EVM decimal id, or the Starknet SN_MAIN felt).
string
Chain id in
0x hex.string
Gateway proxy — the
approve() + createOrder() target.string
Token contract to send.
string
Token symbol.
number
Token decimals.
string
Order amount in token subunits.
string
amount + senderFee in token subunits. Approve this on the token
before calling createOrder — the Gateway pulls amount + senderFee.string
Rate as fixed-point (fiat-per-token × 100).
string
Fee recipient address.
string
Sender fee in token subunits.
string
Refund target — equals
returnAddress.string
Base64 RSA-encrypted recipient blob (the Gateway
messageHash argument).string
Destination fiat code.
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"]
}
}
}