Skip to main content
POST
/
agents
/
transfer
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": "agent_abc123",
    "to_agent_id": "agent_xyz789",
    "amount": "100000.00",
    "pin": "1234",
    "description": "Daily float allocation"
  }'

{
  "success": true,
  "message": "Float transferred successfully",
  "transaction_id": "txn_transfer_abc123",
  "amount": "100,000.00 SLE",
  "from_balance": "1,400,000.00 SLE",
  "to_balance": "600,000.00 SLE"
}
Allows super-agents to transfer float balance to their sub-agents.

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)

​
Body Parameters

​
from_agent_id
string
required
Source agent (super-agent) UUID
​
to_agent_id
string
required
Destination agent (sub-agent) UUID
​
amount
string
required
Amount to transfer
​
pin
string
required
Source agent’s 4-digit PIN
​
description
string
Transfer description

​
Response

​
success
boolean
Whether transfer succeeded
​
transaction_id
string
Transfer transaction ID
​
from_balance
string
Super-agent’s new balance
​
to_balance
string
Sub-agent’s new balance

​
Examples

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": "agent_abc123",
    "to_agent_id": "agent_xyz789",
    "amount": "100000.00",
    "pin": "1234",
    "description": "Daily float allocation"
  }'

{
  "success": true,
  "message": "Float transferred successfully",
  "transaction_id": "txn_transfer_abc123",
  "amount": "100,000.00 SLE",
  "from_balance": "1,400,000.00 SLE",
  "to_balance": "600,000.00 SLE"
}

​
Rules

Hierarchy

Only super-agent to own sub-agent transfers

Balance Check

Source must have sufficient float

​
Errors

StatusCodeDescription
400INVALID_AMOUNTInvalid amount format
400INVALID_PINPIN verification failed
400INSUFFICIENT_FLOATInsufficient balance
401UNAUTHORIZEDInvalid API key
403FORBIDDENNot authorized for this transfer
404NOT_FOUNDAgent not found
500INTERNAL_ERRORServer error

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Body

application/json

Transfer details

​
amount
integer
required
​
sub_agent_id
string
required
​
super_agent_id
string

Optional - auto-detected from logged-in user if not provided

Response

OK

The response is of type object.