> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strails.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Key concepts for working with the Strails API: async processing, wallets, amount formats, and response codes

# Core Concepts

Understanding these concepts will help you integrate the Strails API correctly and avoid common pitfalls.

## Asynchronous Processing

All blockchain operations return a **`requestId`** immediately and process in the background:

```json theme={null}
{ "requestId": "req_abc123", "status": "processing" }
```

This keeps API responses fast (\~200ms) while complex operations (wallet creation, token minting, swaps) complete reliably. Track the final status via [webhooks](/api-reference/webhook-events) or by polling the relevant status endpoint.

## Virtual Accounts

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

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

See the [Virtual Accounts Guide](/virtual-accounts-guide) for account types and deposit flows.

## Wallet System

Fintechs operate with three wallet types:

| Wallet                                    | Holds            | Control                                             |
| ----------------------------------------- | ---------------- | --------------------------------------------------- |
| [Multi-Chain Wallet](/multi-chain-wallet) | cNGN, USDC, USDT | Strails-controlled HSM managed wallet               |
| [Smart Wallet](/smart-wallet)             | cNGN, USDC, USDT | Fintech or Strails-controlled smart contract wallet |
| [MPC 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 a 5-minute price lock
* Self-trading prevention built-in
* Auto-approval of trades that meet your set threshold via dedicated virtual machines

Learn more in [Orderbook Management](/api-reference/orderbook-management) and [Trading Management](/api-reference/trading-management).

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

See [Webhook Events](/api-reference/webhook-events) for payload details.

## 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 theme={null}
{
  "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 the **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 |

**JavaScript conversion (token operations only):**

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

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

<Warning>
  **Key takeaway:** Fiat endpoints use regular Naira amounts. Only blockchain/token operations use wei format with decimals.
</Warning>

## Response Format

All API responses follow a consistent structure.

**Success (HTTP 200):**

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

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

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

### Response Codes

| Code | Meaning          |
| ---- | ---------------- |
| `00` | Success          |
| `01` | Validation Error |
| `02` | Not Found        |
| `03` | Unauthorized     |
| `04` | Rate Limited     |
| `05` | Internal Error   |

For detailed request/response payloads per endpoint, see [Request & Response Formats](/payload-formats).