curl --request POST \
  --url https://crypto.westminister.tech/api/v1/auth/orders \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "b523ed51-a7e0-4c53-8ac2-3c0b7e1c9cd5",
  "vendor_id": "5c81c005-1c52-4e0d-85e2-862ee1cdd4d0",
  "offer_id": "7c9a9311-7e7d-4739-9abc-34f7db00ff19",
  "usdt_amount": "1200.00",
  "fiat_amount": "175200.00",
  "fiat_currency": "KES",
  "wallet_address": 4.085896624744069e+47,
  "status": "pending",
  "payment_method": "mpesa",
  "expires_at": "2025-12-31T23:59:59Z",
  "order_type": "ON_RAMP_BUY"
}
'

{
  "id": "233e6fe7-b022-42a6-b57e-37df3b36e93f",
  "customer_id": "b523ed51-a7e0-4c53-8ac2-3c0b7e1c9cd5",
  "vendor_id": "5c81c005-1c52-4e0d-85e2-862ee1cdd4d0",
  "offer_id": "7c9a9311-7e7d-4739-9abc-34f7db00ff19",
  "usdt_amount": "1200.00000000",
  "fiat_amount": "175200.00",
  "fiat_currency": "KES",
  "wallet_address": 4.085896624744069e+47,
  "status": "pending",
  "payment_method": "mpesa",
  "payment_txn_id": {
    "String": "",
    "Valid": false
  },
  "blockchain_txn_hash": {
    "String": "",
    "Valid": false
  },
  "expires_at": "2025-12-31T23:59:59Z",
  "completed_at": {
    "Time": "0001-01-01T00:00:00Z",
    "Valid": false
  },
  "created_at": "2025-12-12T07:47:59.755991Z",
  "updated_at": "2025-12-12T07:47:59.755991Z",
  "deleted_at": {
    "Time": "0001-01-01T00:00:00Z",
    "Valid": false
  },
  "merchant_request_id": {
    "String": "",
    "Valid": false
  },
  "checkout_request_id": {
    "String": "",
    "Valid": false
  },
  "mpesa_receipt_number": {
    "String": "",
    "Valid": false
  },
  "payment_phone_number": {
    "String": "",
    "Valid": false
  },
  "order_type": "ON_RAMP_BUY",
  "escrow_wallet_address": {
    "String": "",
    "Valid": false
  },
  "escrow_network": {
    "String": "",
    "Valid": false
  },
  "escrow_reference": {
    "String": "",
    "Valid": false
  },
  "deposit_tx_hash": {
    "String": "",
    "Valid": false
  },
  "deposit_confirmations": 0,
  "deposit_detected_at": {
    "Time": "0001-01-01T00:00:00Z",
    "Valid": false
  }
}

Orders

Create Order (On-Ramp Or Off-Ramp)

Creates a new order for buying or selling cryptocurrency (USDT) with fiat currency (KES via mobile money).

Order Flows

On-Ramp Flow (ON_RAMP_BUY)

Customer buys USDT with fiat currency (KES).

1. Customer creates order → Status: "pending"
2. Customer initiates mobile money payment via STK Push
3. System receives mobile money payment confirmation
4. Vendor sends USDT to customer's wallet address
5. Order status → "completed"

Key Points:

Customer pays fiat first (mobile money)
Vendor sends USDT to customer’s wallet
No escrow wallet needed
payout_phone not required

Off-Ramp Flow (OFF_RAMP_SELL)

Customer sells USDT for fiat currency (KES).

1. Customer creates order → Status: "awaiting_crypto"
   └─ System generates unique escrow wallet address
2. Customer sends USDT to escrow wallet address
3. System detects deposit → Status: "crypto_received"
4. System initiates mobile money payout to customer
5. Order status → "completed"

Key Points:

Customer sends USDT to escrow first
System generates unique escrow wallet per order (dynamic address)
System sends mobile money payout after deposit confirmation
payout_phone is required
wallet_address is used to detect network (Tron/Ethereum) for escrow generation

Field Requirements

Field	On-Ramp	Off-Ramp	Notes
`customer_id`	✅ Required	✅ Required	Customer UUID
`vendor_id`	✅ Required	✅ Required	Vendor UUID
`offer_id`	✅ Required	✅ Required	Offer UUID
`usdt_amount`	✅ Required	✅ Required	Amount in USDT
`fiat_amount`	✅ Required	✅ Required	Amount in fiat currency
`fiat_currency`	✅ Required	✅ Required	Currency code (e.g., KES)
`wallet_address`	✅ Required	✅ Required	Customer’s wallet (on-ramp: receives USDT, off-ramp: detects network)
`payment_method`	✅ Required	✅ Required	Payment method (e.g., mpesa)
`order_type`	✅ Required	✅ Required	ON_RAMP_BUY or OFF_RAMP_SELL
`payout_phone`	❌ Not used	✅ Required	mobile money phone number for payout
`status`	⚪ Optional	⚪ Optional	Defaults: “pending” (on-ramp) or “awaiting_crypto” (off-ramp)
`expires_at`	✅ Required	✅ Required	Order expiration (RFC3339 format)

POST

api

auth

orders

curl --request POST \
  --url https://crypto.westminister.tech/api/v1/auth/orders \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "b523ed51-a7e0-4c53-8ac2-3c0b7e1c9cd5",
  "vendor_id": "5c81c005-1c52-4e0d-85e2-862ee1cdd4d0",
  "offer_id": "7c9a9311-7e7d-4739-9abc-34f7db00ff19",
  "usdt_amount": "1200.00",
  "fiat_amount": "175200.00",
  "fiat_currency": "KES",
  "wallet_address": 4.085896624744069e+47,
  "status": "pending",
  "payment_method": "mpesa",
  "expires_at": "2025-12-31T23:59:59Z",
  "order_type": "ON_RAMP_BUY"
}
'

{
  "id": "233e6fe7-b022-42a6-b57e-37df3b36e93f",
  "customer_id": "b523ed51-a7e0-4c53-8ac2-3c0b7e1c9cd5",
  "vendor_id": "5c81c005-1c52-4e0d-85e2-862ee1cdd4d0",
  "offer_id": "7c9a9311-7e7d-4739-9abc-34f7db00ff19",
  "usdt_amount": "1200.00000000",
  "fiat_amount": "175200.00",
  "fiat_currency": "KES",
  "wallet_address": 4.085896624744069e+47,
  "status": "pending",
  "payment_method": "mpesa",
  "payment_txn_id": {
    "String": "",
    "Valid": false
  },
  "blockchain_txn_hash": {
    "String": "",
    "Valid": false
  },
  "expires_at": "2025-12-31T23:59:59Z",
  "completed_at": {
    "Time": "0001-01-01T00:00:00Z",
    "Valid": false
  },
  "created_at": "2025-12-12T07:47:59.755991Z",
  "updated_at": "2025-12-12T07:47:59.755991Z",
  "deleted_at": {
    "Time": "0001-01-01T00:00:00Z",
    "Valid": false
  },
  "merchant_request_id": {
    "String": "",
    "Valid": false
  },
  "checkout_request_id": {
    "String": "",
    "Valid": false
  },
  "mpesa_receipt_number": {
    "String": "",
    "Valid": false
  },
  "payment_phone_number": {
    "String": "",
    "Valid": false
  },
  "order_type": "ON_RAMP_BUY",
  "escrow_wallet_address": {
    "String": "",
    "Valid": false
  },
  "escrow_network": {
    "String": "",
    "Valid": false
  },
  "escrow_reference": {
    "String": "",
    "Valid": false
  },
  "deposit_tx_hash": {
    "String": "",
    "Valid": false
  },
  "deposit_confirmations": 0,
  "deposit_detected_at": {
    "Time": "0001-01-01T00:00:00Z",
    "Valid": false
  }
}

Body

application/json

customer_id

string<uuid>

required

Customer UUID who is placing the order

vendor_id

string<uuid>

required

Vendor UUID offering the trade

offer_id

string<uuid>

required

Offer UUID that this order is based on

usdt_amount

string

required

Amount of USDT in the order (e.g., "1200.00")

fiat_amount

string

required

Equivalent fiat amount (e.g., "175200.00")

fiat_currency

string

required

Fiat currency code (e.g., "KES")

Example:

"KES"

wallet_address

string

required

Customer's wallet address. Used differently based on order type:

On-ramp (ON_RAMP_BUY): Address where customer will receive USDT
Off-ramp (OFF_RAMP_SELL): Used to detect network (Tron if starts with "T", Ethereum otherwise) Must be a valid Tron (TRC20) or Ethereum (ERC20) address.

payment_method

string

required

Payment method for fiat transactions

Example:

"mpesa"

order_type

enum<string>

required

Order type determines the transaction flow:

ON_RAMP_BUY: Customer buys crypto with fiat (mobile money → USDT)
OFF_RAMP_SELL: Customer sells crypto for fiat (USDT → mobile money)

Available options:

ON_RAMP_BUY,

ON_RAMP_SELL,

OFF_RAMP_BUY,

OFF_RAMP_SELL

status

enum<string>

Order status. If not provided, defaults to:

On-ramp: "pending" (waiting for mobile money payment)
Off-ramp: "awaiting_crypto" (waiting for USDT deposit to escrow)

Available options:

pending,

processing,

confirming,

completed,

cancelled,

awaiting_crypto

expires_at

string<date-time>

Order expiration timestamp (RFC3339 format, e.g., "2025-12-31T23:59:59Z")

payout_phone

string

Phone number for receiving mobile money payout (MSISDN format, e.g., "254727648169").

Required for: OFF_RAMP_SELL orders only
Not used in: ON_RAMP_BUY orders Format: Country code + number without leading zeros (e.g., 2547XXXXXXXX for Kenya)

Response

201 - application/json

Order created

string<uuid>

customer_id

string<uuid>

vendor_id

string<uuid>

Liquidity provider (publisher). API name vendor_id.

offer_id

string<uuid> | null

Liquidity listing id. API name offer_id. Nullable for custodial remittance orders.

asset

string | null

crypto_amount

string

usdt_amount

string | null

Backward-compatible alias for crypto_amount

fiat_amount

string

fiat_currency

string

wallet_address

string

status

enum<string>

Available options:

pending,

processing,

confirming,

completed,

cancelled,

failed

payment_method

string

e.g., mpesa

payment_txn_id

object

Database-style nullable string wrapper

Show child attributes

blockchain_txn_hash

object

Database-style nullable string wrapper

Show child attributes

expires_at

string<date-time>

completed_at

object

Database-style nullable time wrapper

Show child attributes

created_at

string<date-time>

updated_at

string<date-time>

deleted_at

object

Database-style nullable time wrapper

Show child attributes

merchant_request_id

object

Database-style nullable string wrapper

Show child attributes

checkout_request_id

object

Database-style nullable string wrapper

Show child attributes

mpesa_receipt_number

object

Database-style nullable string wrapper

Show child attributes

payment_phone_number

object

Database-style nullable string wrapper

Show child attributes

order_type

enum<string>

Available options:

ON_RAMP_BUY,

ON_RAMP_SELL,

OFF_RAMP_BUY,

OFF_RAMP_SELL

order_subtype

enum<string>

Distinguishes standard flows from remittance off-ramp and custodial remittance. Legacy rows are backfilled as standard_onramp/standard_offramp.

Available options:

standard_onramp,

standard_offramp,

remittance_offramp,

custodial_remittance_offramp

sender_name

object

Database-style nullable string wrapper

Show child attributes

sender_country

object

Database-style nullable string wrapper

Show child attributes

sender_phone

object

Database-style nullable string wrapper

Show child attributes

escrow_wallet_address

object

Database-style nullable string wrapper

Show child attributes

escrow_network

object

Database-style nullable string wrapper

Show child attributes

escrow_reference

object

Database-style nullable string wrapper

Show child attributes

deposit_tx_hash

object

Database-style nullable string wrapper

Show child attributes

deposit_confirmations

integer

deposit_detected_at

object

Database-style nullable time wrapper

Show child attributes

List Orders (Paginated)Create Remittance Off-Ramp Order