---
updatedAt: 2026-06-04T14:10:24.000Z
agentTools:
projectIndex: https://c-vmch.readme.io/llms.txt
---
# Create conversion order 🔒 (deprecated)
Create a new conversion order that will be processed by the liquidity network.
**Order Flow:**
**Offramp (USDC → NGN):**
1. Order created with PENDING status
2. User sends USDC to the temporary wallet address returned
3. System detects deposit and triggers fulfillment
4. LP sends NGN to beneficiary bank account
5. Order marked as FULFILLED
**Onramp (NGN → USDC):**
1. Order created with PENDING status
2. User deposits NGN to the virtual bank account returned
3. System detects deposit and triggers fulfillment
4. LP sends USDC to destination wallet address
5. Order marked as FULFILLED
**Timeouts:**
- Orders expire after 30 minutes if no deposit is received
- Expired orders are automatically cancelled
**Refunds:**
- If fulfillment fails, funds are refunded to the refundAddress (offramp) or source account (onramp)
**NOTE: ** This endpoint is deprecated. Please switch to the [Create a new request](https://c-vmch.readme.io/reference/requestscontroller_createrequest) endpoint instead.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"paths": {
"/public/order": {
"post": {
"description": "Create a new conversion order that will be processed by the liquidity network.\n\n**Order Flow:**\n\n**Offramp (USDC → NGN):**\n1. Order created with PENDING status\n2. User sends USDC to the temporary wallet address returned\n3. System detects deposit and triggers fulfillment\n4. LP sends NGN to beneficiary bank account\n5. Order marked as FULFILLED\n\n**Onramp (NGN → USDC):**\n1. Order created with PENDING status\n2. User deposits NGN to the virtual bank account returned\n3. System detects deposit and triggers fulfillment\n4. LP sends USDC to destination wallet address\n5. Order marked as FULFILLED\n\n**Timeouts:**\n- Orders expire after 30 minutes if no deposit is received\n- Expired orders are automatically cancelled\n\n**Refunds:**\n- If fulfillment fails, funds are refunded to the refundAddress (offramp) or source account (onramp)",
"operationId": "PublicRequestsController_createOrder",
"parameters": [
{
"name": "X-Environment",
"in": "header",
"description": "Environment to use for the request. When using API keys, the environment is determined from the key prefix.",
"required": false,
"schema": {
"type": "string",
"enum": [
"sandbox",
"live"
],
"example": "sandbox"
}
},
{
"name": "X-Platform",
"in": "header",
"description": "Optional platform/application identifier for tracking and analytics",
"required": false,
"schema": {
"type": "string",
"example": "mobile-app-ios"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOrderDto"
},
"examples": {
"offramp-complete": {
"summary": "Offramp: USDC → NGN (Complete)",
"description": "Full offramp order with all fields",
"value": {
"fromAsset": "USDC",
"toAsset": "NGN",
"amount": "100",
"description": "Payment for invoice #INV-2024-001",
"beneficiary": {
"externalId": "user_12345",
"bankAccount": {
"bankCode": "044",
"accountNumber": "0123456789",
"accountName": "John Doe"
}
},
"refundAddress": "GCFXH5C3YQBAW7OKL2AVZFYJ6IHLZN4SXKTWRVQPQG3E5QJWZ7M2UW3K",
"metadata": {
"invoiceId": "INV-2024-001",
"customerId": "cust_abc123"
}
}
},
"offramp-minimal": {
"summary": "Offramp: Minimal required fields",
"description": "Offramp with only required fields",
"value": {
"fromAsset": "USDC",
"toAsset": "NGN",
"amount": "50",
"beneficiary": {
"bankAccount": {
"bankCode": "058",
"accountNumber": "1234567890",
"accountName": "Jane Smith"
}
}
}
},
"onramp-complete": {
"summary": "Onramp: NGN → USDC (Complete)",
"description": "Full onramp order with all fields",
"value": {
"fromAsset": "NGN",
"toAsset": "USDC",
"amount": "150000",
"description": "USDC purchase",
"destinationAddress": "GCFXH5C3YQBAW7OKL2AVZFYJ6IHLZN4SXKTWRVQPQG3E5QJWZ7M2UW3K",
"sender": {
"externalId": "user_67890",
"fullName": "Jane Smith",
"email": "jane@example.com",
"phone": "+2348012345678"
},
"metadata": {
"purpose": "investment"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Order created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderResponseDto"
}
}
}
},
"400": {
"description": "Invalid request data",
"content": {
"application/json": {
"schema": {
"example": {
"statusCode": 400,
"message": "destinationAddress is required for onramp requests",
"error": "Bad Request"
}
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing credentials"
}
},
"security": [
{
"bearer": []
},
{
"aggregator-api-key": []
}
],
"summary": "Create conversion order 🔒 (deprecated)",
"tags": [
"Aggregator Requests"
]
}
}
},
"info": {
"title": "Protocol API",
"description": "## Overview\nCentiiv Protocol is a decentralized liquidity aggregation platform for fiat-to-crypto and crypto-to-fiat conversions. This API enables aggregators, liquidity providers, and applications to integrate with the protocol.\n\n---\n\n## Environments\n\n| Environment | API Key Prefix | Use Case |\n|-------------|----------------|----------|\n| **Sandbox** | `sandbox_*` | Testing and development |\n| **Live** | `live_*` | Production transactions |\n\nThe environment is automatically determined from your API key prefix. You can also override it using the `X-Environment` header.\n\n---\n\n## Authentication Methods\n\n### 1. JWT Bearer Token\nFor dashboard access and management endpoints\n### 2. Aggregator API Key\nFor quote and order endpoints:\n- Header: `X-API-Key: ` (Format: `pk_...` or `sk_...`)\n---\n\n## Transaction Types\n\n### Offramp (Stablecoin → Fiat)\nUser sends crypto, receives fiat to their bank account.\n\n### Onramp (Fiat → Stablecoin)\nUser deposits fiat to virtual account, receives crypto to their wallet.\n\n---\n\n## Fee Structure\n\n| Fee Type | Description | Example |\n|----------|-------------|--------|\n| **PERCENTAGE** | Percentage of transaction amount | 1.5% fee on 1500 rate → 1477.5 effective rate |\n| **SPREAD** | Fixed amount subtracted from rate | 10 spread on 1500 rate → 1490 effective rate |\n| **FIXED** | Flat fee per transaction | $5 fixed fee deducted from output |\n\n",
"version": "1.0.0",
"contact": {}
},
"servers": [
{
"url": "https://api.centiiv.io",
"description": "Production"
},
{
"url": "https://api.staging.centiiv.io",
"description": "Staging"
}
],
"components": {
"securitySchemes": {
"aggregator-api-key": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Aggregator API key. Format: `pk_ENV_xxx` or `sk_ENV_xxx`. Where `ENV` is either `sandbox` or `live`"
},
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http",
"description": "JWT access token."
}
},
"schemas": {
"KenyaMomoSenderDto": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Payment type — always MOMO for Kenya mobile-money deposits",
"enum": [
"MOMO"
],
"example": "MOMO"
},
"network": {
"type": "string",
"description": "Mobile network the depositor uses",
"enum": [
"MPESA"
],
"example": "MPESA"
},
"accountNumber": {
"type": "string",
"description": "Kenyan phone number that will fund the deposit (the account Brails pulls from).",
"example": "+25475049021"
},
"accountName": {
"type": "string",
"description": "Name of the person who will make the deposit",
"example": "May Dean"
}
},
"required": [
"type",
"network",
"accountNumber",
"accountName"
]
},
"BankAccountDto": {
"type": "object",
"properties": {
"bankCode": {
"type": "string",
"description": "Bank code (e.g., CBN code for Nigerian banks)",
"example": "044"
},
"accountNumber": {
"type": "string",
"description": "Bank account number (NUBAN for Nigeria)",
"example": "0123456789"
},
"accountName": {
"type": "string",
"description": "Account holder name (must match bank records)",
"example": "John Doe"
},
"routingNumber": {
"type": "string",
"description": "Routing number (for US banks)",
"example": "021000021"
},
"swift": {
"type": "string",
"description": "SWIFT/BIC code (for international transfers)",
"example": "CITIUS33"
},
"iban": {
"type": "string",
"description": "IBAN (for European banks)",
"example": "GB82WEST12345698765432"
}
},
"required": [
"bankCode",
"accountNumber",
"accountName"
]
},
"BeneficiaryDto": {
"type": "object",
"properties": {
"externalId": {
"type": "string",
"description": "Your internal user/customer ID for tracking. Helps correlate orders with your users.",
"example": "user_12345"
},
"bankAccount": {
"description": "Bank account details where fiat will be sent",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountDto"
}
]
}
},
"required": [
"bankAccount"
]
},
"SenderDto": {
"type": "object",
"properties": {
"externalId": {
"type": "string",
"description": "Your internal user/customer ID for tracking",
"example": "user_67890"
},
"fullName": {
"type": "string",
"description": "Full legal name of the sender (for compliance)",
"example": "Jane Smith"
},
"email": {
"type": "string",
"description": "Email address for notifications",
"example": "jane@example.com"
},
"phone": {
"type": "string",
"description": "Phone number with country code",
"example": "+2348012345678"
}
}
},
"CreateOrderDto": {
"type": "object",
"properties": {
"fromAsset": {
"type": "string",
"description": "Source asset to convert from",
"example": "USDC",
"enum": [
"USDC",
"EURC",
"USDT",
"CNGN",
"USDT0",
"NGN",
"CNY",
"UGX",
"KES",
"GHS",
"USD",
"XAF",
"XOF",
"CDF",
"ETB",
"ZAR",
"TZS"
]
},
"toAsset": {
"type": "string",
"description": "Destination asset to convert to",
"example": "NGN",
"enum": [
"USDC",
"EURC",
"USDT",
"CNGN",
"USDT0",
"NGN",
"CNY",
"UGX",
"KES",
"GHS",
"USD",
"XAF",
"XOF",
"CDF",
"ETB",
"ZAR",
"TZS"
]
},
"amount": {
"type": "number",
"description": "Amount to convert in source asset units. Must be positive and within allowed limits.",
"example": 100,
"minimum": 0.01
},
"network": {
"type": "string",
"description": "Blockchain network this order runs on. Must match an existing rail for the (fromAsset, toAsset, network) triple. Defaults to STELLAR when omitted.",
"enum": [
"STELLAR",
"SOLANA",
"ARC",
"BASE",
"ARBITRUM",
"OPTIMISM",
"POLYGON",
"AVALANCHE",
"APTOS",
"ETHEREUM",
"BSC",
"HYPEREVM"
],
"default": "STELLAR",
"example": "STELLAR"
},
"description": {
"type": "string",
"description": "Human-readable description for this order. Useful for your records and customer support.",
"example": "Payment for invoice #INV-2024-001",
"maxLength": 500
},
"beneficiary": {
"description": "Beneficiary information for OFFRAMP orders (Crypto → Fiat). Required when converting crypto to fiat.",
"allOf": [
{
"$ref": "#/components/schemas/BeneficiaryDto"
}
]
},
"destinationAddress": {
"type": "string",
"description": "Wallet address for ONRAMP orders (Fiat → Crypto). Required when converting fiat to crypto. Must be a valid blockchain address.",
"example": "0x1234...abcd (chain-specific wallet address)"
},
"refundAddress": {
"type": "string",
"description": "Wallet address for refunds if OFFRAMP fails. Recommended for all offramp orders.",
"example": "0x1234...abcd (chain-specific wallet address)"
},
"sender": {
"description": "Sender information for ONRAMP orders. Helps with compliance and customer identification.",
"allOf": [
{
"$ref": "#/components/schemas/SenderDto"
}
]
},
"depositor": {
"description": "Depositor details for mobile-money (KES) ONRAMP orders. Required when fromAsset is KES — the deposit is pulled from the payer MPESA account, which must be provided for compliance.",
"allOf": [
{
"$ref": "#/components/schemas/KenyaMomoSenderDto"
}
]
},
"webhookUrl": {
"type": "string",
"description": "Webhook URL to receive real-time order status updates. Must be a publicly accessible HTTPS endpoint.",
"example": "https://your-api.com/webhooks/cent-protocol"
},
"targetNodeId": {
"type": "string",
"description": "Target a specific LP node for this order. Only use if you have a preferred LP arrangement.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"metadata": {
"type": "object",
"description": "Custom metadata to attach to this order. Stored and returned in webhooks and order queries.",
"example": {
"invoiceId": "INV-001",
"customerId": "cust_abc123"
}
}
},
"required": [
"fromAsset",
"toAsset",
"amount"
]
},
"TemporaryWalletDto": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Wallet address for token deposits (OFFRAMP only)",
"example": "chain-specific-wallet-address"
},
"memo": {
"type": "string",
"description": "Memo to include with the deposit (OFFRAMP only)",
"example": "123456"
},
"expiresAt": {
"format": "date-time",
"type": "string",
"description": "When this temporary wallet/account expires",
"example": "2026-01-29T11:00:00.000Z"
},
"virtualAccountNumber": {
"type": "string",
"description": "Virtual account number for NGN deposits (ONRAMP only)",
"example": "8012345678"
},
"virtualAccountName": {
"type": "string",
"description": "Virtual account name (ONRAMP only)",
"example": "Cent Protocol/Jane Smith"
},
"virtualBankName": {
"type": "string",
"description": "Bank name for virtual account (ONRAMP only)",
"example": "Wema Bank"
},
"virtualBankCode": {
"type": "string",
"description": "Bank code for virtual account (ONRAMP only)",
"example": "035"
}
}
},
"OrderResponseDto": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique order identifier (UUID)",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"orderIdHex": {
"type": "object",
"description": "Order ID hash for blockchain reference",
"example": "a1b2c3d4e5f6789...",
"nullable": true
},
"status": {
"type": "string",
"description": "Current order status",
"example": "PENDING",
"enum": [
"PENDING",
"PROCESSING",
"FULFILLED",
"FAILED",
"EXPIRED",
"REFUNDED"
]
},
"fromAsset": {
"type": "string",
"description": "Source asset",
"example": "USDC"
},
"toAsset": {
"type": "string",
"description": "Destination asset",
"example": "NGN"
},
"inputAmount": {
"type": "string",
"description": "Amount being converted (in source asset)",
"example": "100.00"
},
"rate": {
"type": "string",
"description": "Exchange rate (LP rate) applied to this order, before fee deductions",
"example": "1485.50"
},
"receivableAmount": {
"type": "string",
"description": "Amount user will receive after fees are deducted from the converted value (in destination asset)",
"example": "148550.00"
},
"fee": {
"type": "string",
"description": "Aggregator fee. Deducted from the converted output (DEDUCTED mode) or charged on top (ADDED mode).",
"example": "1500.00"
},
"totalToPay": {
"type": "string",
"description": "Gross amount the payer must deposit, in the source asset. Equals inputAmount in DEDUCTED fee mode, or inputAmount + fee in ADDED fee mode.",
"example": "100.00"
},
"createdAt": {
"format": "date-time",
"type": "string",
"description": "When the order was created",
"example": "2026-01-29T10:30:00.000Z"
},
"temporaryWallet": {
"description": "Deposit instructions. For OFFRAMP: blockchain wallet address. For ONRAMP: Virtual bank account details.",
"allOf": [
{
"$ref": "#/components/schemas/TemporaryWalletDto"
}
]
},
"beneficiary": {
"type": "object",
"description": "Beneficiary details for offramp orders"
},
"environment": {
"type": "string",
"description": "Environment this order was created in. LIVE for production, SANDBOX for testing.",
"example": "LIVE",
"enum": [
"LIVE",
"SANDBOX"
]
},
"description": {
"type": "string",
"description": "Order description if provided",
"example": "Payment for invoice #INV-2024-001"
}
},
"required": [
"id",
"orderIdHex",
"status",
"fromAsset",
"toAsset",
"inputAmount",
"rate",
"receivableAmount",
"fee",
"totalToPay",
"createdAt",
"environment"
]
}
}
}
}
```