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

# Agents

> Agent network management - registration, funding, and cash-in operations

<Info>
  Agents are field operators who provide cash-in/cash-out services to subscribers. OLIVE supports a hierarchical agent network with super-agents and sub-agents.
</Info>

## Agent Hierarchy

<CardGroup cols={2}>
  <Card title="Super-Agent" icon="crown" color="#f59e0b">
    **Regional managers**

    * Register sub-agents
    * Fund sub-agent float
    * View network performance
    * Higher commission tier
  </Card>

  <Card title="Sub-Agent" icon="user" color="#6366f1">
    **Field agents**

    * Process cash-in/cash-out
    * Receive float from super-agent
    * Earn per-transaction commission
    * Mobile-based operations
  </Card>
</CardGroup>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Register Agent" icon="plus" href="/api-reference/agents/register">
    `POST /api/v1/agents`

    Register new super/sub agent
  </Card>

  <Card title="Get Agent" icon="user" href="/api-reference/agents/get">
    `GET /api/v1/agents/{id}`

    Get agent details
  </Card>

  <Card title="List Agents" icon="list" href="/api-reference/agents/list">
    `GET /api/v1/agents`

    List agents with filters
  </Card>

  <Card title="Lookup Agent" icon="search" href="/api-reference/agents/lookup">
    `GET /api/v1/agents/lookup`

    Find agent by phone number
  </Card>

  <Card title="Fund Agent" icon="plus-circle" href="/api-reference/agents/fund">
    `POST /api/v1/agents/{id}/fund`

    Add float to agent account
  </Card>

  <Card title="Cash-In" icon="arrow-down" href="/api-reference/agents/cashin">
    `POST /api/v1/agents/cashin`

    Credit subscriber wallet
  </Card>

  <Card title="Transfer Float" icon="arrow-right" href="/api-reference/agents/transfer">
    `POST /api/v1/agents/transfer`

    Transfer to sub-agent
  </Card>

  <Card title="Get Balance" icon="wallet" href="/api-reference/agents/balance">
    `GET /api/v1/agents/{id}/balance`

    Check agent float balance
  </Card>
</CardGroup>

***

## Agent Object

```json theme={null}
{
  "id": "agent_abc123",
  "type": "super_agent",
  "business_name": "ABC Money Services",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+23277123456",
  "email": "john@abcmoney.sl",
  "location": "Freetown",
  "status": "active",
  "float_balance": 5000000,
  "float_balance_formatted": "5,000,000.00 SLE",
  "commission_tier": "standard",
  "settlement_mode": "instant",
  "parent_agent_id": null,
  "sub_agent_count": 12,
  "created_at": "2025-01-01T10:00:00Z"
}
```

***

## Agent Status

<CardGroup cols={3}>
  <Card title="Active" icon="circle-check" color="#10b981">
    Can process transactions
  </Card>

  <Card title="Suspended" icon="pause" color="#f59e0b">
    Temporarily disabled
  </Card>

  <Card title="Terminated" icon="x" color="#ef4444">
    Permanently deactivated
  </Card>
</CardGroup>

***

## Agent Lifecycle

<Steps>
  <Step title="Registration">
    Admin or super-agent registers new agent with business details
  </Step>

  <Step title="Account Setup">
    System creates agent account and user credentials
  </Step>

  <Step title="Float Funding">
    OLIVE or super-agent adds initial float balance
  </Step>

  <Step title="Operations">
    Agent processes cash-in/cash-out for subscribers
  </Step>

  <Step title="Settlement">
    Agent settles with OLIVE or super-agent periodically
  </Step>
</Steps>

***

## Cash-In Flow

<Steps>
  <Step title="Subscriber Arrives">
    Customer brings cash to agent location
  </Step>

  <Step title="Identify Subscriber">
    Agent looks up subscriber by phone or card
  </Step>

  <Step title="Process Cash-In">
    Agent enters amount and PIN to process
  </Step>

  <Step title="Balance Update">
    Agent float debited, subscriber credited
  </Step>

  <Step title="Confirmation">
    Both receive WhatsApp notification
  </Step>
</Steps>

***

## Commission Structure

| Agent Type  | Cash-In | Cash-Out |
| ----------- | ------- | -------- |
| Super-Agent | 0.3%    | 0.5%     |
| Sub-Agent   | 0.2%    | 0.3%     |

<Info>
  Commission is earned from fees charged to subscribers and credited instantly to agent balance.
</Info>

***

## Common Workflows

<AccordionGroup>
  <Accordion title="Register New Sub-Agent" icon="plus">
    1. Super-agent logs into dashboard
    2. Navigate to Agent Management
    3. Call `POST /api/v1/agents` with `agent_type: "sub_agent"`
    4. Include `parent_agent_id` referencing super-agent
    5. New agent receives credentials via WhatsApp
  </Accordion>

  <Accordion title="Fund Sub-Agent Float" icon="coins">
    1. Super-agent checks own balance
    2. Call `POST /api/v1/agents/{sub_agent_id}/fund`
    3. Amount transferred from super to sub-agent
    4. Both balances updated atomically
  </Accordion>

  <Accordion title="Process Customer Cash-In" icon="arrow-down">
    1. Agent looks up subscriber by phone
    2. Collects cash from customer
    3. Call `POST /api/v1/agents/cashin`
    4. Agent float decreases, subscriber wallet increases
    5. Commission credited to agent
  </Accordion>
</AccordionGroup>

***

## Permissions

| Role         | Can Register | Can Fund       | Can View    |
| ------------ | ------------ | -------------- | ----------- |
| System Admin | Super + Sub  | Any agent      | All         |
| Super-Agent  | Sub only     | Own sub-agents | Own network |
| Sub-Agent    | None         | None           | Own profile |

***

## Related

<CardGroup cols={2}>
  <Card title="Compliance" icon="shield" href="/api-reference/compliance/overview">
    Agent transaction monitoring
  </Card>

  <Card title="Suspicious Activity" icon="alert-triangle" href="/api-reference/suspicious-transactions/overview">
    Flag unusual agent behavior
  </Card>
</CardGroup>