Accounts API — ClawdGo Docs

POST /v1/accounts

Provision a new agent account. Creates a Solana PDA for the agent and an associated USDC SPL token account.

Request body

Field	Type	Required	Description
`name`	string	required	Human-readable label for this agent account. Not unique — used for display only.
`metadata`	object	optional	Arbitrary key-value pairs stored alongside the account record. Not used by ClawdGo — for your own reference.

Response — 201 Created

json

{
  "account_id": "acct_01j8k4x9p2qrst7yz",
  "name": "research-agent-prod",
  "solana_address": "9xTz4KqR8mYvPn3SdFgHj6WbCeAuLo1XkQi5NtZpMwV",
  "usdc_token_account": "7mZp2VbQnXeYjLo9KrTzFdCgWqA3ShNkRi4UwPtMxHs",
  "balance_usdc": "0.000000",
  "status": "active",
  "policy": {
    "max_single_transfer": null,
    "max_daily_spend": null,
    "allowed_counterparties": null,
    "require_memo": false,
    "paused": false
  },
  "created_at": "2024-01-15T10:32:00Z"
}

GET /v1/accounts

List all agent accounts for the authenticated operator.

Query parameters

Param	Type	Description
`limit`	integer	Number of results per page. Default: 20, max: 100.
`cursor`	string	Pagination cursor from previous response.
`status`	string	Filter by status: `active` \| `paused`

Response — 200 OK

json

{
  "data": [ /* Account objects */ ],
  "cursor": "eyJpZCI6ImFjY3Rf...",
  "has_more": true
}

GET /v1/accounts/:id

Retrieve a single account by ID.

Path parameters

Param	Description
`id`	The `account_id` returned when the account was created.

GET /v1/accounts/:id/balance

Get the current USDC balance for an account. Balance is read from the on-chain USDC SPL token account — always reflects the live on-chain state.

Response — 200 OK

json

{
  "account_id": "acct_01j8k4x9p2qrst7yz",
  "balance_usdc": "342.500000",
  "last_updated": "2024-01-15T11:04:33Z"
}

GET /v1/accounts/:id/transactions

List transaction history for an account, including settled transfers, policy rejections, and deposits.

Query parameters

Param	Type	Description
`limit`	integer	Max results. Default: 25, max: 100.
`cursor`	string	Pagination cursor.
`status`	string	`settled` \| `rejected` \| `all` (default: all)
`since`	ISO8601	Return transactions after this timestamp.