Transfer Float

POST/agents/transferOpen in the API playground →

Info

Allows super-agents to transfer float balance to their sub-agents.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Body Parameters

from_agent_idstringbodyrequired

Source agent (super-agent) UUID

to_agent_idstringbodyrequired

Destination agent (sub-agent) UUID

amountstringbodyrequired

Amount to transfer

pinstringbodyrequired

Source agent's 4-digit PIN

descriptionstringbody

Transfer description

---

Response

successboolean

Whether transfer succeeded

transaction_idstring

Transfer transaction ID

from_balancestring

Super-agent's new balance

to_balancestring

Sub-agent's new balance

---

Examples

Request

cURL

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"
  }'

Response

200 Success

{
  "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"
}

400 Insufficient Balance

{
  "success": false,
  "error": "Insufficient float balance",
  "code": "INSUFFICIENT_FLOAT",
  "available": 50000,
  "required": 100000
}

403 Not Sub-Agent

{
  "error": "Target agent is not your sub-agent",
  "code": "FORBIDDEN"
}

---

Rules

Hierarchy

Only super-agent to own sub-agent transfers

Balance Check

Source must have sufficient float

---

Errors

Status	Code	Description
400	INVALID_AMOUNT	Invalid amount format
400	INVALID_PIN	PIN verification failed
400	INSUFFICIENT_FLOAT	Insufficient balance
401	UNAUTHORIZED	Invalid API key
403	FORBIDDEN	Not authorized for this transfer
404	NOT_FOUND	Agent not found
500	INTERNAL_ERROR	Server error