Fund Agent

POST/agents/{id}/fundOpen in the API playground →

Info

Adds float balance to an agent's account. System admins can fund any agent. Super-agents can only fund their sub-agents.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Path Parameters

idstringpathrequired

Agent UUID to fund (e.g., agent_abc123)

Body Parameters

amountstringbodyrequired

Amount to add (e.g., 500000.00 or 500000)

descriptionstringbody

Funding description/reference

---

Response

successboolean

Whether funding succeeded

transaction_idstring

Funding transaction ID

new_balancestring

Agent's new float balance

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/agents/agent_abc123/fund" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500000.00",
    "description": "Weekly float top-up"
  }'

Response

200 Success

{
  "success": true,
  "message": "Agent funded successfully",
  "transaction_id": "txn_fund_abc123",
  "amount": "500,000.00 SLE",
  "new_balance": "1,500,000.00 SLE",
  "funded_by": "admin@smartpay.sl"
}

403 Forbidden

{
  "error": "Not authorized to fund this agent",
  "code": "FORBIDDEN"
}

---

Funding Sources

SmartPay Admin

System admin funds from SmartPay pool

Super-Agent

Super-agent transfers own float to sub-agent

---

Permissions

Funder Role	Can Fund
System Admin	Any agent
Super-Agent	Own sub-agents only
Sub-Agent	None

---

Errors

Status	Code	Description
400	INVALID_AMOUNT	Invalid amount format
401	UNAUTHORIZED	Invalid API key
403	FORBIDDEN	Not authorized to fund
403	INSUFFICIENT_FLOAT	Super-agent has insufficient balance
404	NOT_FOUND	Agent not found
500	INTERNAL_ERROR	Server error