Skip to main content

​
Allocate Budget

Allocate budget from treasury to an agent.
cURL
curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetAgentId": "123e4567-e89b-12d3-a456-426614174000",
    "lamports": 100000000,
    "reason": "Initial trading budget",
    "sourceAgentId": "optional-source-agent-id"
  }' \
  http://localhost:3000/api/v1/treasury/allocate

​
Request Body

​
targetAgentId
string
required
Agent UUID receiving the allocation
​
lamports
number
required
Amount to allocate in lamports (must be positive)
​
reason
string
default:"treasury allocation"
Reason for allocation (1-256 characters)
​
sourceAgentId
string
Optional source agent UUID (if reallocating from another agent)

​
Response

​
allocationId
string
required
Unique allocation identifier
​
targetAgentId
string
required
Target agent UUID
​
sourceAgentId
string
Source agent UUID (if provided)
​
lamports
number
required
Allocated amount
​
reason
string
required
Allocation reason
​
timestamp
string
required
ISO 8601 timestamp
{
  "status": "success",
  "data": {
    "allocationId": "abc123-def456-...",
    "targetAgentId": "123e4567-e89b-12d3-a456-426614174000",
    "lamports": 100000000,
    "reason": "Initial trading budget",
    "timestamp": "2026-03-08T12:00:00.000Z"
  }
}

​
Rebalance Budget

Rebalance budget between two agents.
cURL
curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAgentId": "123e4567-e89b-12d3-a456-426614174000",
    "targetAgentId": "234f5678-f90c-23e4-b827-537725285111",
    "lamports": 50000000,
    "reason": "Rebalancing after performance review"
  }' \
  http://localhost:3000/api/v1/treasury/rebalance

​
Request Body

​
sourceAgentId
string
required
Agent UUID to transfer budget from
​
targetAgentId
string
required
Agent UUID to transfer budget to
​
lamports
number
required
Amount to transfer in lamports (must be positive)
​
reason
string
default:"treasury rebalance"
Reason for rebalance (1-256 characters)

​
Response

​
rebalanceId
string
required
Unique rebalance identifier
​
sourceAgentId
string
required
Source agent UUID
​
targetAgentId
string
required
Target agent UUID
​
lamports
number
required
Transferred amount
​
reason
string
required
Rebalance reason
​
timestamp
string
required
ISO 8601 timestamp
{
  "status": "success",
  "data": {
    "rebalanceId": "xyz789-abc012-...",
    "sourceAgentId": "123e4567-e89b-12d3-a456-426614174000",
    "targetAgentId": "234f5678-f90c-23e4-b827-537725285111",
    "lamports": 50000000,
    "reason": "Rebalancing after performance review",
    "timestamp": "2026-03-08T12:00:00.000Z"
  }
}

​
Agent Budget Operations

Agent budgets are tracked and enforced automatically:

​
Get Agent Budget

See Agent Budget API for retrieving current budget and spending. 
curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/budget

​
Budget Enforcement

Budgets are enforced at transaction execution:
  1. Check available budget before transaction
  2. Deduct from budget on successful transaction
  3. Reject if insufficient budget remaining
  4. Reset daily spending at midnight UTC

​
Treasury Workflows

​
Initial Setup

1

Create Agents

Create agents with initial budgets:
curl -X POST \
  -H "x-api-key: dev-api-key" \
  -d '{
    "name": "Trading Bot Alpha",
    "executionMode": "autonomous",
    "budgetLamports": 100000000
  }' \
  http://localhost:3000/api/v1/agents
2

Allocate Additional Budget

Add more budget as needed:
curl -X POST \
  -H "x-api-key: dev-api-key" \
  -d '{
    "targetAgentId": "agent-id",
    "lamports": 50000000,
    "reason": "Additional allocation for high-volume trading"
  }' \
  http://localhost:3000/api/v1/treasury/allocate
3

Monitor Spending

Track budget usage:
curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/agents/agent-id/budget

​
Performance-Based Rebalancing

1

Review Agent Performance

Check transaction success rates and profitability via audit events:
curl -H "x-api-key: dev-api-key" \
     "http://localhost:3000/api/v1/audit/events?agentId=agent-id"
2

Rebalance Budgets

Shift budget from underperforming to high-performing agents:
curl -X POST \
  -H "x-api-key: dev-api-key" \
  -d '{
    "sourceAgentId": "underperforming-agent-id",
    "targetAgentId": "high-performing-agent-id",
    "lamports": 25000000,
    "reason": "Performance-based rebalancing"
  }' \
  http://localhost:3000/api/v1/treasury/rebalance
3

Update Capabilities

Adjust agent capabilities based on performance:
curl -X PUT \
  -H "x-api-key: dev-api-key" \
  -d '{"allowedIntents": [...]}' \
  http://localhost:3000/api/v1/agents/agent-id/capabilities

​
Budget Constraints

​
Transaction Execution

When an agent executes a transaction:
  1. Budget Check: 
    if (transaction.estimatedCost > agent.budgetLamports - agent.spentLamportsToday) {
  return deny("Insufficient budget");
}
  2. Policy Evaluation:
    • Spending limits
    • Protocol restrictions
    • Risk thresholds
  3. Execution:
    • Transaction submitted
    • Budget updated on confirmation
  4. Daily Reset:
    • spentLamportsToday resets at midnight UTC
    • Total budgetLamports persists

​
Audit Trail

All treasury operations are logged to audit events: 
curl -H "x-api-key: dev-api-key" \
     "http://localhost:3000/api/v1/audit/events?entityType=agent"
Events include:
  • treasury.allocate
  • treasury.rebalance
  • agent.budget.updated
  • agent.budget.exceeded
  • agent.budget.reset

​
Best Practices

Set conservative initial budgets and increase based on performance
Monitor daily spending to detect anomalies early
Use descriptive reasons for all allocations and rebalances
Implement budget alerts when spending exceeds thresholds
Review budget usage regularly via audit events
Coordinate with policy limits - budgets and policies work together

​
Example: Multi-Agent Treasury

# Create three agents with different strategies

# Conservative agent - 100 SOL budget
curl -X POST -H "x-api-key: dev-api-key" \
  -d '{"name": "Conservative Bot", "budgetLamports": 100000000000}' \
  http://localhost:3000/api/v1/agents

# Moderate agent - 50 SOL budget
curl -X POST -H "x-api-key: dev-api-key" \
  -d '{"name": "Moderate Bot", "budgetLamports": 50000000000}' \
  http://localhost:3000/api/v1/agents

# Aggressive agent - 25 SOL budget (testing)
curl -X POST -H "x-api-key: dev-api-key" \
  -d '{"name": "Aggressive Bot", "budgetLamports": 25000000000}' \
  http://localhost:3000/api/v1/agents

# After 1 week: rebalance based on performance
# If aggressive bot performs well, increase budget:

curl -X POST -H "x-api-key: dev-api-key" \
  -d '{
    "sourceAgentId": "conservative-bot-id",
    "targetAgentId": "aggressive-bot-id",
    "lamports": 25000000000,
    "reason": "Aggressive strategy outperforming - increasing allocation"
  }' \
  http://localhost:3000/api/v1/treasury/rebalance

​
Transaction Types

Treasury operations can be executed via:
  1. Direct API calls (shown above)
  2. Agent execution with treasury_allocate or treasury_rebalance transaction types
  3. CLI commands: 
    npm run cli -- treasury allocate --target-agent-id <id> --lamports <amount>
npm run cli -- treasury rebalance --source-agent-id <id> --target-agent-id <id> --lamports <amount>

Build docs developers (and LLMs) love

Get started for freeTalk to us