# StRails API

Welcome to Strails - the REST API for **cNGN, USDC, USDT stablecoin** integration enabling onramp and offramp to naira fiat, P2P onchain Forex trading, 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)
* Batch process onramp/offramp operations
* Configure custom fee structures for your users
* Manage liquidity with dual-wallet system (Smart Wallet + MPC Vault)

**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

### Virtual Accounts

Every user gets a **dedicated Nigerian bank account** that automatically converts deposits to cNGN (or auto-swaps to USDC/USDT). The account is active for 30 minutes after creation, perfect for one-time or recurring funding.

### cNGN Token

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

* `500000000` = 500 cNGN
* `1000000` = 1 cNGN

### FX Orderbook

Fintechs can place **limit orders** to trade cNGN ↔ USDC with other fintechs. Trades are settled on-chain with escrow-based safety (5-minute fund lock). [Learn more →](/api-reference/orderbook-management.md)

### Webhooks

All critical operations (wallet creation, deposits, trades, withdrawals) send **real-time notifications** to your configured webhook URL with HMAC signature verification option. [Learn more →](/api-reference/webhook-events.md)

***

## 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_abc123",
    "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)

***

## Key Features

### Enterprise Security

* **MPC Vault Integration** - No direct private key exposure
* **ED25519 Encryption** - Optional end-to-end payload encryption
* **HMAC Webhook Signatures** - Verify authenticity of notifications
* **IP Allowlisting** - Restrict API access by IP address
* **BVN Verification** - Nigerian bank verification via IdentityPass

### FX Trading Features

* Real-time orderbook with price discovery
* Escrow-based trade settlement (5-minute lock)
* Self-trading prevention
* Automatic liquidity matching
* Minimum 1.5% price improvement vs AMM

### Auto-Swap & Liquidity

* Self-custody of trade liquidity
* Dynamic slippage protection
* Automatic best-path routing
* Gas-optimized batch operations

***

## 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 in this site
* **Support Email:** <technical-support@stablesrail.io>
* **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:** April 2026\
**API Version:** v1.0


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.