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

# Agent Network

> Understanding OLIVE's cash-in/cash-out agent network

# Agent Network

Agents are local businesses authorized to handle cash transactions for OLIVE users.

## Agent Types

| Type          | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `super_agent` | Top-level agent (bank, large business). Cannot have parent. |
| `sub_agent`   | Individual shop/kiosk. Must have `parent_agent_id`.         |

***

## Agent Status

| Status      | Description                        |
| ----------- | ---------------------------------- |
| `active`    | Can perform transactions (default) |
| `inactive`  | Account dormant                    |
| `suspended` | Temporarily blocked by admin       |

***

## Commission Tiers

| Tier | Top-up Rate | Withdrawal Rate |
| ---- | ----------- | --------------- |
| 1    | 1.0%        | 0.5%            |
| 2    | 1.5%        | 0.75%           |
| 3    | 2.0%        | Higher          |

Tier must be 1, 2, or 3.

***

## Settlement Modes

| Mode      | Description                           |
| --------- | ------------------------------------- |
| `instant` | Commission paid immediately (default) |
| `weekly`  | Accumulated, paid weekly              |
| `monthly` | Accumulated, paid monthly             |

***

## Agent Fields

| Field              | Type      | Description                   |
| ------------------ | --------- | ----------------------------- |
| `id`               | TEXT      | Unique agent ID               |
| `agent_type`       | TEXT      | `super_agent` or `sub_agent`  |
| `parent_agent_id`  | TEXT      | For sub-agents (FK to agents) |
| `agent_name`       | TEXT      | Display name                  |
| `business_name`    | TEXT      | Registered business name      |
| `contact_person`   | TEXT      | Primary contact               |
| `phone_number`     | TEXT      | Unique phone                  |
| `email`            | TEXT      | Business email                |
| `business_address` | TEXT      | Physical address              |
| `district`         | TEXT      | Sierra Leone district         |
| `location`         | TEXT      | Location description          |
| `float_balance`    | INTEGER   | Working capital (SLE)         |
| `balance`          | BIGINT    | Account balance               |
| `commission_tier`  | INTEGER   | 1, 2, or 3                    |
| `tier_level`       | INTEGER   | Legacy tier field             |
| `settlement_mode`  | TEXT      | instant/weekly/monthly        |
| `kyc_documents`    | TEXT      | KYC doc URLs                  |
| `kyc_document_url` | TEXT      | Primary KYC doc               |
| `agent_pin_hash`   | TEXT      | PIN hash (SHA256)             |
| `status`           | TEXT      | active/inactive/suspended     |
| `created_at`       | TIMESTAMP | Registration date             |

***

## Validation Rules

**Super Agent:**

* Cannot have `parent_agent_id`
* Business name required
* Contact person required
* Phone required
* Commission tier 1-3

**Sub Agent:**

* Must have `parent_agent_id`
* Same field requirements as super agent

***

## Float Operations

| Operation                 | Effect on Float |
| ------------------------- | --------------- |
| Cash-in from customer     | Decreases       |
| Cash-out to customer      | Increases       |
| Float transfer from super | Increases       |
| Float transfer to sub     | Decreases       |

***

## Agent PIN

Every agent has a 4-digit PIN:

* Hashed: `SHA256(pin)` (no salt)
* Required for transaction authorization
* Validated before any float operation

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Integration" icon="book" href="/guides/agent-integration">
    Complete guide
  </Card>

  <Card title="Agent API" icon="code" href="/api-reference/agents/overview">
    API endpoints
  </Card>

  <Card title="Fees" icon="coins" href="/concepts/fees">
    Commission rates
  </Card>
</CardGroup>