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

> Complete guide for integrating with OLIVE agent network

# Agent Integration Guide

Complete guide for integrating with the OLIVE agent network for cash-in, cash-out, and float management operations.

## Overview

OLIVE agents are authorized individuals or businesses that facilitate cash transactions for subscribers who may not have direct access to digital banking.

<CardGroup cols={3}>
  <Card title="Cash-In" icon="plus-circle">
    Customer deposits cash, agent credits wallet
  </Card>

  <Card title="Cash-Out" icon="minus-circle">
    Customer withdraws cash, agent debits wallet
  </Card>

  <Card title="Float Transfer" icon="arrows-left-right">
    Transfer float between agents
  </Card>
</CardGroup>

***

## Agent Types

| Type         | Description                                      | Capabilities                           |
| ------------ | ------------------------------------------------ | -------------------------------------- |
| Master Agent | Top-level agent, typically a bank/large business | Fund sub-agents, view all transactions |
| Sub-Agent    | Retail point (shop, kiosk)                       | Handle customer transactions           |

### Agent Hierarchy

```mermaid theme={null}
graph TD
    OLIVE[OLIVE Platform] --> MA1[Master Agent 1]
    OLIVE --> MA2[Master Agent 2]
    MA1 --> SA1[Sub-Agent 1.1]
    MA1 --> SA2[Sub-Agent 1.2]
    MA2 --> SA3[Sub-Agent 2.1]
```

***

## Prerequisites

Before integrating:

<Steps>
  <Step title="Agent Registration">
    Agent must be registered in OLIVE with a unique ID and phone number
  </Step>

  <Step title="Float Funding">
    Master agent must fund sub-agent float via `/agents/transfer`
  </Step>

  <Step title="PIN Setup">
    Agent must have a transaction PIN configured
  </Step>

  <Step title="API Key">
    Obtain API key with `agent` scope
  </Step>
</Steps>

***

## Authentication

Agent operations use standard API key authentication:

```bash theme={null}
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents/cashin" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

***

## Cash-In Operation

Customer deposits cash with agent, who credits the customer's wallet.

### Flow

<Steps>
  <Step title="Customer Provides Info">
    Customer shows phone number or NFC card
  </Step>

  <Step title="Agent Looks Up Customer">
    Agent calls `/agents/lookup` to verify subscriber
  </Step>

  <Step title="Collect Cash">
    Agent collects physical cash from customer
  </Step>

  <Step title="Process Cash-In">
    Agent calls `/agents/cashin` with amount
  </Step>

  <Step title="Confirmation">
    Both agent and customer receive confirmation
  </Step>
</Steps>

### API Call

```bash theme={null}
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents/cashin" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_123abc",
    "subscriber_phone": "+23277123456",
    "amount": 100000,
    "pin": "1234"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "transaction_id": "txn_abc123",
  "message": "Cash-in successful",
  "data": {
    "subscriber_name": "John Doe",
    "amount": 100000,
    "currency": "SLE",
    "new_balance": 250000,
    "agent_float": 400000
  }
}
```

<Warning>
  Agent float is debited on cash-in. Ensure sufficient float before processing.
</Warning>

***

## Float Transfer

Transfer float between agents (typically master to sub-agent).

### API Call

```bash theme={null}
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents/transfer" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_agent_id": "master_agent_001",
    "to_agent_id": "sub_agent_123",
    "amount": 500000,
    "pin": "1234"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "transaction_id": "txn_xyz789",
  "message": "Float transfer successful",
  "data": {
    "from_agent_float": 1500000,
    "to_agent_float": 800000
  }
}
```

***

## Agent Lookup

Look up agent details by phone number:

```bash theme={null}
curl -X GET "https://demo.api.vultlocal.com/api/v1/agents/lookup?phone=+23277123456" \
  -H "Authorization: Bearer olive_live_xxx"
```

```json theme={null}
{
  "agent": {
    "id": "agent_123abc",
    "name": "John's Shop",
    "phone": "+23277123456",
    "type": "sub_agent",
    "float_balance": 500000,
    "status": "active"
  }
}
```

***

## Balance Check

Get agent float balance:

```bash theme={null}
curl -X GET "https://demo.api.vultlocal.com/api/v1/agents/agent_123abc/balance" \
  -H "Authorization: Bearer olive_live_xxx"
```

```json theme={null}
{
  "agent_id": "agent_123abc",
  "float_balance": 500000,
  "currency": "SLE",
  "today_transactions": 15,
  "today_volume": 750000
}
```

***

## Error Handling

| Error Code             | Meaning                         | Resolution                      |
| ---------------------- | ------------------------------- | ------------------------------- |
| `INSUFFICIENT_FLOAT`   | Agent doesn't have enough float | Request float from master agent |
| `INVALID_PIN`          | Wrong transaction PIN           | Retry with correct PIN          |
| `SUBSCRIBER_NOT_FOUND` | Phone/card not registered       | Help customer register          |
| `AGENT_SUSPENDED`      | Agent account suspended         | Contact support                 |
| `DAILY_LIMIT_EXCEEDED` | Agent hit daily limit           | Wait for next day               |

### Error Response Example

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FLOAT",
    "message": "Agent does not have sufficient float for this transaction",
    "details": {
      "requested": 100000,
      "available": 50000
    }
  }
}
```

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Float Management" icon="coins">
    * Monitor float levels regularly
    * Set up low-float alerts
    * Reconcile daily with master agent
  </Card>

  <Card title="Security" icon="shield">
    * Never share transaction PIN
    * Verify customer identity
    * Report suspicious activity
  </Card>

  <Card title="Operations" icon="clipboard-list">
    * Keep physical cash secure
    * Issue receipts for all transactions
    * End-of-day reconciliation
  </Card>

  <Card title="Compliance" icon="scale-balanced">
    * Follow KYC requirements
    * Report large transactions
    * Maintain transaction records
  </Card>
</CardGroup>

***

## Webhooks (Optional)

Subscribe to agent transaction events:

```json theme={null}
{
  "event": "agent.cashin.completed",
  "data": {
    "agent_id": "agent_123abc",
    "transaction_id": "txn_abc123",
    "amount": 100000,
    "timestamp": "2025-01-15T10:30:00Z"
  }
}
```

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Lookup API" icon="magnifying-glass" href="/api-reference/agents/lookup">
    Look up agent by phone
  </Card>

  <Card title="Cash-In API" icon="plus-circle" href="/api-reference/agents/cashin">
    Process cash deposits
  </Card>

  <Card title="Float Transfer API" icon="arrows-left-right" href="/api-reference/agents/transfer">
    Transfer float between agents
  </Card>

  <Card title="Agent Balance API" icon="wallet" href="/api-reference/agents/balance">
    Check agent float
  </Card>
</CardGroup>