Treasury

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

string

required

Agent UUID receiving the allocation

number

required

Amount to allocate in lamports (must be positive)

string

default:"treasury allocation"

Reason for allocation (1-256 characters)

string

Optional source agent UUID (if reallocating from another agent)

Response

string

required

Unique allocation identifier

string

required

Target agent UUID

string

Source agent UUID (if provided)

number

required

Allocated amount

string

required

Allocation reason

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

string

required

Agent UUID to transfer budget from

string

required

Agent UUID to transfer budget to

number

required

Amount to transfer in lamports (must be positive)

string

default:"treasury rebalance"

Reason for rebalance (1-256 characters)

Response

string

required

Unique rebalance identifier

string

required

Source agent UUID

string

required

Target agent UUID

number

required

Transferred amount

string

required

Rebalance reason

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:

Check available budget before transaction
Deduct from budget on successful transaction
Reject if insufficient budget remaining
Reset daily spending at midnight UTC

Treasury Workflows

Initial Setup

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

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

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

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"

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

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:

Budget Check:

if (transaction.estimatedCost > agent.budgetLamports - agent.spentLamportsToday) {
  return deny("Insufficient budget");
}

Policy Evaluation:
- Spending limits
- Protocol restrictions
- Risk thresholds
Execution:
- Transaction submitted
- Budget updated on confirmation
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:

Direct API calls (shown above)
Agent execution with treasury_allocate or treasury_rebalance transaction types

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>

Overview

Endpoints

Allocate Budget

Request Body

Response

Rebalance Budget

Request Body

Response

Agent Budget Operations

Get Agent Budget

Budget Enforcement

Treasury Workflows

Initial Setup

Performance-Based Rebalancing

Budget Constraints

Transaction Execution

Audit Trail

Best Practices

Example: Multi-Agent Treasury

Transaction Types

​Allocate Budget

​Request Body

​Response

​Rebalance Budget

​Request Body

​Response

​Agent Budget Operations

​Get Agent Budget

​Budget Enforcement

​Treasury Workflows

​Initial Setup

​Performance-Based Rebalancing

​Budget Constraints

​Transaction Execution

​Audit Trail

​Best Practices

​Example: Multi-Agent Treasury

​Transaction Types

Allocate Budget

Request Body

Response

Rebalance Budget

Request Body

Response

Agent Budget Operations

Get Agent Budget

Budget Enforcement

Treasury Workflows

Initial Setup

Performance-Based Rebalancing

Budget Constraints

Transaction Execution

Audit Trail

Best Practices

Example: Multi-Agent Treasury

Transaction Types