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

# API Reference

> Complete REST API reference for the OLIVE Payment Platform

<Info>
  **Base URL**: `https://demo.api.vultlocal.com` (Demo) | `http://localhost:8080` (Development)
</Info>

## Quick Access

<CardGroup cols={3}>
  <Card title="Subscribers" icon="users" color="#6366f1" href="/api-reference/subscribers/register">
    User accounts, KYC, and profile management
  </Card>

  <Card title="Cards" icon="credit-card" color="#8b5cf6" href="/api-reference/cards/link">
    NFC card linking, blocking, and management
  </Card>

  <Card title="Wallet" icon="wallet" color="#10b981" href="/api-reference/wallet/balance">
    Balances, transfers, and transactions
  </Card>

  <Card title="Agents" icon="building-2" color="#f59e0b" href="/api-reference/agents/register">
    Agent network and cash-in operations
  </Card>

  <Card title="POS" icon="store" color="#ec4899" href="/api-reference/pos/payment">
    Point-of-sale terminal integrations
  </Card>

  <Card title="Admin" icon="shield" color="#ef4444" href="/api-reference/admin/login">
    Authentication and user management
  </Card>
</CardGroup>

***

## Authentication

<Tabs>
  <Tab title="API Key">
    ```bash theme={null}
    Authorization: Bearer olive_live_xxxxxxxxxxxxx
    ```

    Best for: Server-to-server integrations, POS terminals
  </Tab>

  <Tab title="JWT Token">
    ```bash theme={null}
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    ```

    Best for: Dashboard users, session-based access
  </Tab>

  <Tab title="HMAC Signature">
    ```bash theme={null}
    X-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    X-Partner-ID: VULT
    ```

    Best for: Partner integrations (VULT, external systems)
  </Tab>
</Tabs>

<Card title="Authentication Guide" icon="key" href="/api-reference/authentication">
  Learn about authentication methods, token refresh, and security best practices
</Card>

***

## API Categories

<AccordionGroup>
  <Accordion title="Subscribers" icon="users">
    Manage subscriber accounts, KYC levels, and profile information.

    | Endpoint                                  | Description             |
    | ----------------------------------------- | ----------------------- |
    | `POST /api/v1/subscribers`                | Register new subscriber |
    | `GET /api/v1/subscribers/:id`             | Get subscriber details  |
    | `GET /api/v1/subscribers`                 | List all subscribers    |
    | `PUT /api/v1/subscribers/:id`             | Update subscriber       |
    | `POST /api/v1/subscribers/:id/block`      | Block subscriber        |
    | `POST /api/v1/subscribers/:id/unblock`    | Unblock subscriber      |
    | `POST /api/v1/subscribers/:id/verify-pin` | Verify PIN              |
    | `POST /api/v1/subscribers/:id/change-pin` | Change PIN              |
  </Accordion>

  <Accordion title="Cards" icon="credit-card">
    NFC card management, linking, and child cards.

    | Endpoint                             | Description             |
    | ------------------------------------ | ----------------------- |
    | `POST /api/v1/cards/link`            | Link card to subscriber |
    | `POST /api/v1/cards/child`           | Create child card       |
    | `GET /api/v1/cards/:serial`          | Get card details        |
    | `GET /api/v1/cards`                  | List all cards          |
    | `POST /api/v1/cards/:serial/block`   | Block card              |
    | `POST /api/v1/cards/:serial/unblock` | Unblock card            |
    | `POST /api/v1/cards/upload-csv`      | Bulk upload cards       |
  </Accordion>

  <Accordion title="Wallet" icon="wallet">
    Financial operations, transfers, and transaction history.

    | Endpoint                                | Description         |
    | --------------------------------------- | ------------------- |
    | `GET /api/v1/balance/:user_id`          | Get wallet balance  |
    | `GET /api/v1/transactions`              | Transaction history |
    | `POST /api/v1/wallet/transfer`          | Internal transfer   |
    | `POST /api/v1/wallet/transfer-p2p`      | P2P by card serial  |
    | `POST /api/v1/wallet/fund-from-vult`    | Fund from VULT      |
    | `POST /api/v1/wallet/account-statement` | Generate statement  |
  </Accordion>

  <Accordion title="Agents" icon="building-2">
    Agent network management and cash-in operations.

    | Endpoint                         | Description           |
    | -------------------------------- | --------------------- |
    | `POST /api/v1/agents`            | Register agent        |
    | `GET /api/v1/agents/:id`         | Get agent details     |
    | `GET /api/v1/agents`             | List agents           |
    | `POST /api/v1/agents/:id/fund`   | Fund agent float      |
    | `POST /api/v1/agents/cashin`     | Agent cash-in         |
    | `POST /api/v1/agents/transfer`   | Transfer to sub-agent |
    | `GET /api/v1/agents/:id/balance` | Get agent balance     |
  </Accordion>

  <Accordion title="POS" icon="store">
    Point-of-sale terminal operations.

    | Endpoint                | Description                |
    | ----------------------- | -------------------------- |
    | `POST /pos/payment`     | Process payment            |
    | `POST /pos/verify-card` | Verify card before payment |
    | `POST /pos/refund`      | Refund transaction         |
    | `POST /pos/lookup-card` | Look up card info          |
  </Accordion>

  <Accordion title="Processors" icon="cpu">
    Payment processor (merchant) management.

    | Endpoint                                  | Description        |
    | ----------------------------------------- | ------------------ |
    | `POST /api/v1/processors`                 | Create processor   |
    | `GET /api/v1/processors/:id`              | Get processor      |
    | `GET /api/v1/processors`                  | List processors    |
    | `POST /api/v1/processors/:id/suspend`     | Suspend processor  |
    | `POST /api/v1/processors/:id/transfer`    | Processor transfer |
    | `GET /api/v1/processors/:id/transactions` | Processor history  |
  </Accordion>

  <Accordion title="Compliance" icon="shield-check">
    Fraud detection and compliance monitoring.

    | Endpoint                                     | Description           |
    | -------------------------------------------- | --------------------- |
    | `POST /api/v1/compliance/check`              | Run compliance check  |
    | `GET /api/v1/compliance/alerts`              | List alerts           |
    | `POST /api/v1/compliance/alerts`             | Create alert          |
    | `POST /api/v1/compliance/alerts/:id/resolve` | Resolve alert         |
    | `GET /api/v1/compliance/rules`               | List monitoring rules |
    | `GET /api/v1/account-rules/:kyc_level`       | Get KYC limits        |
  </Accordion>

  <Accordion title="Admin" icon="lock">
    System administration and user management.

    | Endpoint                      | Description    |
    | ----------------------------- | -------------- |
    | `POST /api/v1/admin/login`    | User login     |
    | `POST /api/v1/admin/refresh`  | Refresh token  |
    | `POST /api/v1/admin/logout`   | Logout         |
    | `GET /api/v1/admin/me`        | Current user   |
    | `POST /api/v1/admin/users`    | Create user    |
    | `POST /api/v1/admin/api-keys` | Create API key |
    | `GET /api/v1/audit/logs`      | Audit logs     |
  </Accordion>
</AccordionGroup>

***

## Request & Response

<Tabs>
  <Tab title="Request Format">
    ```bash theme={null}
    curl -X POST https://demo.api.vultlocal.com/api/v1/wallet/transfer-p2p \
      -H "Authorization: Bearer olive_live_xxx" \
      -H "Content-Type: application/json" \
      -H "X-Request-ID: unique-id-123" \
      -d '{
        "sender_id": "sub_abc123",
        "recipient_card_serial": "OLIV0002",
        "amount": "5000",
        "pin": "1234"
      }'
    ```
  </Tab>

  <Tab title="Success Response">
    ```json theme={null}
    {
      "success": true,
      "message": "Transfer successful",
      "transaction_id": "txn_xyz789",
      "sender_new_balance": "45,000.00 SLE",
      "fee_amount": "50.00 SLE"
    }
    ```
  </Tab>

  <Tab title="Error Response">
    ```json theme={null}
    {
      "error": "Insufficient balance",
      "code": "INSUFFICIENT_FUNDS",
      "details": {
        "available": 3000,
        "required": 5050
      }
    }
    ```
  </Tab>
</Tabs>

***

## HTTP Status Codes

<CardGroup cols={2}>
  <Card title="Success Codes" icon="circle-check" color="#10b981">
    * **200** OK - Request succeeded
    * **201** Created - Resource created
    * **204** No Content - Deleted successfully
  </Card>

  <Card title="Client Errors" icon="circle-x" color="#f59e0b">
    * **400** Bad Request - Invalid input
    * **401** Unauthorized - Auth required
    * **403** Forbidden - No permission
    * **404** Not Found - Resource missing
    * **429** Rate Limited - Too many requests
  </Card>
</CardGroup>

***

## Rate Limiting

<Warning>
  Default limit: **100 requests/second** per API key. Contact support for higher limits.
</Warning>

Rate limit headers in response:

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
```

***

## Explore APIs

<CardGroup cols={2}>
  <Card title="Postman Collection" icon="flask" href="/api-reference/overview">
    Import our Postman collection for quick testing
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="/api-reference/overview">
    Download the OpenAPI 3.0 specification
  </Card>
</CardGroup>