> For the complete documentation index, see [llms.txt](https://docs.strails.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.strails.co/readme.md).

# StRails API

Welcome to Strails - the REST API for **cNGN, USDC, USDT stablecoin** integration enabling onramp and offramp to naira fiat, P2P onchain FX trading, multi-chain wallet infrastructure, and transaction management.

***

## What Can You Build?

* **Fintech Platforms** - White-label cNGN integration for payment services
* **P2P Exchange** - Trade cNGN ↔ USDC/USDT with other fintechs on the orderbook
* **Wallet Applications** - Fund cNGN on user wallets via NGN bank transfers
* **Payout Systems** - Convert cNGN to fiat and send to Nigerian bank accounts
* **Auto-Swap Services** - Automatically convert NGN → cNGN → USDC/USDT

***

## Choose Your Integration Path

### Fintech Partner Integration

**For platforms integrating Strails into their services** (payment processors, exchanges, fintech companies)

**Key Capabilities:**

* Create virtual accounts for your end-users with BVN verification
* Trade on the FX orderbook (fintech-to-fintech P2P trading)
* Configure custom fee structures for your users so we collect your fees for you
* Manage liquidity with multi-wallet system ([Smart Wallet](/documentation/smart-wallet.md) + MPC Vault + Managed Wallet)

**Start Here:** [Fintech Quick Start ↓](#fintech-quick-start)

***

### Direct User Integration

**For applications serving individual users** (wallet apps, DeFi interfaces, consumer apps)

**Key Capabilities:**

* Onboard users with BVN verification
* Fund wallets via NGN bank transfer → auto-swap to USDC/USDT
* Withdraw cNGN to Nigerian bank accounts
* Track transaction history and status
* Receive real-time webhook notifications

**Start Here:** [User Quick Start ↓](#user-quick-start)

***

## Core Concepts

### Asynchronous Processing

All blockchain operations return a **requestId** immediately and process in the background. Track status via webhooks or polling:

```json
{ "requestId": "req_abc123", "status": "processing" }
```

This ensures fast API responses (\~200ms) while complex operations (wallet creation, token minting, swaps) complete reliably.

### Virtual Accounts

Every user gets a dedicated Nigerian bank account that automatically converts deposits to cNGN. Key features:

* Bank accounts generated via licensed payment integration
* Auto-swap option: NGN → cNGN → USDC/USDT in a single flow
* Depositor details captured for compliance

### cNGN Token

**Important:** cNGN uses **6 decimals** (not 18 like ETH)

* `500000000` = 500 cNGN
* `1000000` = 1 cNGN
* Fiat operations use regular Naira amounts; only blockchain responses use raw format

### Multi Wallet System (Fintech Partners)

Fintechs operate with three wallet types:

| Wallet                                         | Holds            | Control                                             |
| ---------------------------------------------- | ---------------- | --------------------------------------------------- |
| Multi-chain Wallet                             | cNGN, USDC, USDT | Strails-controlled HSM managed wallet               |
| [Smart Wallet](/documentation/smart-wallet.md) | cNGN, USDC, USDT | Fintech or Strails-controlled smart contract wallet |
| MPC Wallet                                     | USDC, USDT       | Fintech-controlled with MPC signing                 |

Tokens live in smart wallets and managed wallets.

### FX Orderbook

Fintechs can trade cNGN ↔ USDC/USDT with other fintechs:

* **Limit orders:** Set your price and wait for counterparties
* **Market orders:** Execute instantly at best available price
* Escrow-based settlement with 5-minute price lock
* Self-trading prevention built-in
* Sanction for Fintechs that fail to approve manual trade execution
* Auto-approval of trade execution that meets Fintech's set trade threshold via dedicated virtual machines

[Learn more →](/api-reference/orderbook-management.md)

### Webhooks

All critical operations send real-time notifications to your configured webhook URL:

* Wallet creation, deposits, trades, withdrawals
* HMAC signature verification (optional but recommended)
* Retry logic with exponential backoff

[Learn more →](/api-reference/webhook-events.md)

***

## Key Features

### Multi-Chain Support

Deploy wallets and process transactions across multiple blockchains:

* **Base** (primary) - cNGN token operations, FX orderbook
* **EVM Chains** - Ethereum, Polygon, BNB Chain, AssetChain
* **Stellar/Bantu** - Stellar-based network support
* **Solana** - SPL token operations

### Enterprise Security

* **MPC Vault Integration** - No direct private key exposure
* **ED25519 Encryption** - Optional end-to-end payload encryption
* **IP Allowlisting** - Restrict API access by IP address
* **HMAC Webhook Signatures** - Verify notification authenticity

### Cross-Chain Bridging

Transfer tokens between supported networks with callback-based status updates.

***

## Quick Start

Choose your integration path and follow the step-by-step guide:

### Fintech Partner Integration

**Test your API connection:**

```bash
curl -X GET https://beta.stablesrail.io/v1/getfintechwallet \
  -H "x-api-key: YOUR_API_KEY"
```

**What you can do:**

* Create virtual accounts for users
* Trade cNGN ↔ USDC on the FX orderbook
* Configure custom fee structures
* Manage liquidity with dual-wallet system

**Complete Guide:** [Fintech Integration Walkthrough →](/getting-started/implementation-guide.md#fintech-quick-start)

***

### Direct User Integration

**Onboard your first user:**

```bash
curl -X POST https://beta.stablesrail.io/v1/onboarduser \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901",
    "userId": "user_uniqueID",
    "email": "user@example.com",
    "phoneNumber": "+2348012345678"
  }'
```

**What you can do:**

* Fund wallets via NGN bank transfer
* Auto-swap NGN → cNGN → USDC
* Process withdrawals to bank accounts
* Track transactions in real-time

**Complete Guide:** [User Integration Walkthrough →](/getting-started/implementation-guide.md#step-3-onboard-your-first-user)

***

## Response Format

All API responses follow a consistent structure:

**Success (HTTP 200):**

```json
{
  "status": "success",
  "response_code": "00",
  "message": "Operation completed successfully",
  "data": { "requestId": "req_abc123" }
}
```

**Error (HTTP 4xx/5xx):**

```json
{
  "status": "error",
  "response_code": "01",
  "message": "Validation error: Invalid amount",
  "error": { "field": "amount", "reason": "Must be greater than 0" }
}
```

**Response Codes:**

* `00` = Success
* `01` = Validation Error
* `02` = Not Found
* `03` = Unauthorized
* `04` = Rate Limited
* `05` = Internal Error

***

## Important: Amount Formats

The API uses **different amount formats** depending on the operation type:

### Fiat Operations (Onramp/Offramp/Virtual Accounts)

Amounts are in **Naira** (main currency unit):

```json
{
  "amount": 5000    // = ₦5,000 (NOT 5000 kobo)
}
```

**Examples:**

* Create virtual account: `"amount": 5000` → User pays ₦5,000
* Onramp: `"amount": 200` → Costs ₦203 (with fees)
* Offramp: `"amount": 3000` → User receives ₦3,000 in bank

### Token Operations (Blockchain Transfers/Balances)

Amounts use **smallest unit (wei format)** with token decimals:

| Token | Decimals | Example                       |
| ----- | -------- | ----------------------------- |
| cNGN  | 6        | `500000000` = 500 cNGN        |
| USDC  | 6        | `1000000` = 1 USDC            |
| USDT  | 6        | `1000000` = 1 USDT            |
| DAI   | 18       | `1000000000000000000` = 1 DAI |

**Examples:**

* Token balance: `"balance": "500000000"` = 500 cNGN
* Blockchain response: `"amount": "1000000"` = 1 USDC
* FX orderbook: `"minAmount": "500000000"` = 500 cNGN

**JavaScript Conversion (Token Operations Only):**

```javascript
// Blockchain response → Display
const displayAmount = Number("500000000") / 1e6; // = 500 cNGN

// User input → Blockchain request
const rawAmount = String(Math.floor(123.45 * 1e6)); // = "123450000"
```

{% hint style="warning" %}
**Key Takeaway:** Fiat endpoints use regular Naira amounts. Only blockchain/token operations use wei format with decimals.
{% endhint %}

***

## API Documentation

### Getting Started

* [**Authentication & Base URL**](/getting-started/authentication.md) - API keys, rate limits, error codes
* [**Implementation Guide**](/getting-started/implementation-guide.md) - Step-by-step integration

### API Reference

* [User Management](/api-reference/user-management.md) - BVN verification, onboarding, user status
* [Virtual Accounts](/api-reference/virtual-accounts.md) - Bank account generation for deposits
* [Wallet Management](/api-reference/wallet.md) - Fintech wallets, external wallets, balances
* [Transactions](/api-reference/transactions.md) - Onramp, offramp, withdrawals, status checks
* [FX Orderbook](/api-reference/orderbook-management.md) - Create/update/delete limit orders
* [FX Trading](/api-reference/trading-management.md) - Get quotes, execute trades, trade history
* [Fee Management](/api-reference/fee-management-api.md) - Configure fees, withdraw collected fees
* [Fiat Payouts](/api-reference/fiat-payout-management.md) - Bank account management for offramps
* [Configuration](/api-reference/management-api.md) - IP allowlist, webhooks, API key rotation

### Testing & Tools

* [Testing Guide](/testing-and-development/testing-scenarios.md) - Test scenarios and examples
* [Webhook Events](/api-reference/webhook-events.md) - Real-time notification reference
* [Payload Formats](/data-formats/payload-formats.md) - Request/response structures
* [Postman Collection](https://github.com/wrappedcbdc/stablerail-docs/blob/main/postman-collection.json) - Ready-to-use API collection

***

## Support & Resources

* **Full API Reference:** Complete endpoint documentation on this site
* **Postman Collection:** [Download JSON](https://github.com/wrappedcbdc/stablerail-docs/blob/main/postman-collection.json)
* **Implementation Guide:** [Step-by-step walkthrough](/getting-started/implementation-guide.md)

***

**Last updated:** May 2026\
**API Version:** v1.0


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.strails.co/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.