Agent Balances

View and manage token balances for trading agents.

Endpoints Overview

Method	Endpoint	Description
`GET`	`/api/v1/agent-balances`	List balances for an agent
`GET`	`/api/v1/agent-balances/:id`	Get a specific balance
`POST`	`/api/v1/agent-balances`	Create a balance record
`PUT`	`/api/v1/agent-balances/:id`	Update a balance
`DELETE`	`/api/v1/agent-balances/:id`	Delete a balance

All balance endpoints require JWT authentication.

List Balances

Get all token balances for an agent. Includes enriched price information.

GET /api/v1/agent-balances?agentId=:agentId

Query Parameters

Parameter	Type	Required	Description
`agentId`	UUID	Yes	Agent ID
`walletAddress`	string	No	Filter by specific wallet

Response

Success (200)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "tokenAddress": "So11111111111111111111111111111111111111112",
    "tokenSymbol": "SOL",
    "balance": "10.5",
    "lastUpdated": "2025-01-20T10:30:00.000Z",
    "priceSol": 1
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "tokenSymbol": "USDC",
    "balance": "1250.00",
    "lastUpdated": "2025-01-20T10:25:00.000Z",
    "priceSol": 0.0067
  }
]

Response Fields

Field	Type	Description
`id`	UUID	Balance record ID
`agentId`	UUID	Associated agent ID
`walletAddress`	string	Wallet public key
`tokenAddress`	string	Token mint address
`tokenSymbol`	string	Token ticker symbol
`balance`	string	Token balance amount
`lastUpdated`	ISO 8601	Last balance update time
`priceSol`	number	Optional: Current price in SOL

Example

curl -X GET "https://your-instance.com/api/v1/agent-balances?agentId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer <access_token>"

Get Balance

Get a specific balance record by ID.

GET /api/v1/agent-balances/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Balance record ID

Response

Success (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "tokenAddress": "So11111111111111111111111111111111111111112",
  "tokenSymbol": "SOL",
  "balance": "10.5",
  "lastUpdated": "2025-01-20T10:30:00.000Z"
}

Create Balance

Create a new balance record for an agent.

POST /api/v1/agent-balances

Request

{
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "tokenAddress": "So11111111111111111111111111111111111111112",
  "tokenSymbol": "SOL",
  "balance": "10.5"
}

Field	Type	Required	Description
`agentId`	UUID	Yes	Agent ID
`walletAddress`	string	Yes	Wallet public key
`tokenAddress`	string	Yes	Token mint address
`tokenSymbol`	string	Yes	Token ticker symbol
`balance`	string	Yes	Token balance amount

Response

Success (201)

Returns the created balance record.

Update Balance

Update an existing balance record.

PUT /api/v1/agent-balances/:id

Request

{
  "balance": "15.75"
}

Response

Success (200)

Returns the updated balance record.

Delete Balance

Delete a balance record.

DELETE /api/v1/agent-balances/:id

Response

Success (200)

{
  "success": true
}

Related Endpoints

Agents - Manage agents
Agent Positions - View positions
Wallets - Manage wallets

Agents Agent Positions