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

# Introduction

> Rolla Developer API for programmatic transaction management

## Overview

The Rolla Developer API enables you to programmatically manage wallets and retrieve transaction data. Use it to automate financial operations across multiple currencies.

<Info>
  **Amounts**: Unless a route documents otherwise, numeric **`amount`** fields use each currency's **smallest unit** — NGN **kobo** (like the quickstart withdrawal), USD **US cents** (**100** = **\$1.00** USD), etc.
</Info>

**Base URL**: `https://api.rolla.xyz/api/v1/external`

## Authentication

All API endpoints require authentication using an API key. Include your API key in the `X-API-Key` header with every request.

```bash theme={null}
curl -X GET "https://api.rolla.xyz/api/v1/external/banks" \
  -H "X-API-Key: your_api_key_here"
```

<Warning>
  Keep your API key secure. Do not expose it in client-side code or public repositories.
</Warning>

### Obtaining an API Key

API keys can be generated from your [Rolla Dashboard](https://app.rolla.xyz). Navigate to **Settings → API Keys** to create and manage your keys.

### IP Whitelisting

For enhanced security, you can optionally whitelist specific IP addresses for your API key. When enabled, requests from non-whitelisted IPs will be rejected.

## Acting on a tenant account (`X-Account-Id`)

If your business is a Rolla **white-label tenant**, a single API key can act on any account inside your tenancy — your own account, or any account you've onboarded under it. Add the optional **`X-Account-Id`** header naming the target account, and the **entire** request is scoped to that account: onboarding, documents, wallets, funding instructions, payouts, beneficiaries — everything runs as that account.

```bash theme={null}
# Fetch funding instructions for one of your tenant's accounts
curl -X GET "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/funding-instructions" \
  -H "X-API-Key: your_tenant_api_key" \
  -H "X-Account-Id: 3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
```

| Behaviour                                     | Result                                                                     |
| --------------------------------------------- | -------------------------------------------------------------------------- |
| Header omitted                                | The request acts as your own (the API key's) account — standard behaviour. |
| Header set to an account in your tenancy      | The request is scoped to that account.                                     |
| Header set, but your key isn't a tenant key   | `403` — `X-Account-Id` is only available to tenant API keys.               |
| Header naming an account outside your tenancy | `404` — Account not found in your tenancy.                                 |

<Info>
  Accounts you create with a tenant API key (via `POST /accounts`) are automatically added to your tenancy, so you can immediately address them with `X-Account-Id` afterwards. Accounts that onboard themselves through your white-label app are part of your tenancy too.
</Info>

## Response Format

All responses follow a consistent JSON structure:

```json theme={null}
{
  "status": true,
  "message": "Description of the result",
  "data": { ... }
}
```

### Error Responses

When an error occurs, the response will include `status: false` and a descriptive error message:

```json theme={null}
{
  "status": false,
  "message": "Invalid or inactive API key"
}
```

## Rate Limiting

API requests are rate-limited to ensure fair usage. If you exceed the limit, you'll receive a `429 Too Many Requests` response.

## Available Endpoints

| Endpoint        | Method     | Description                                                   |
| --------------- | ---------- | ------------------------------------------------------------- |
| `/banks`        | GET        | List Nigerian banks                                           |
| `/lookup`       | POST       | Validate bank account                                         |
| `/transactions` | GET        | Retrieve transactions                                         |
| `/accounts`     | POST / GET | Onboard and manage additional business or individual accounts |