Agents - Agentic Wallet

Create Agent

Create an autonomous or supervised agent.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trading Bot Alpha",
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "executionMode": "autonomous",
    "allowedIntents": ["transfer_sol", "swap", "query_balance"],
    "budgetLamports": 100000000
  }' \
  http://localhost:3000/api/v1/agents

Request Body

string

required

Agent name (1-128 characters)

string

Wallet UUID for this agent (auto-created if omitted)

enum

default:"autonomous"

autonomous or supervised

array

default:"[transfer_sol, transfer_spl, query_balance]"

Array of allowed transaction types

number

Agent budget in lamports

object

Autonomous execution configuration (see Autonomy Config)

Response

string

required

Agent UUID

string

required

Agent name

string

required

Wallet UUID

enum

required

stopped, running, or paused

enum

required

autonomous or supervised

array

required

Array of allowed transaction types

number

Agent budget

string

required

ISO 8601 timestamp

string

required

ISO 8601 timestamp

Autonomy Configuration

For autonomous agents, configure decision rules and scheduled steps:

{
  "name": "Autonomous Trader",
  "executionMode": "autonomous",
  "autonomy": {
    "enabled": true,
    "mode": "execute",
    "cadenceSeconds": 30,
    "maxActionsPerHour": 60,
    "steps": [
      {
        "id": "periodic-balance-check",
        "type": "query_balance",
        "protocol": "system-program",
        "intent": {},
        "cooldownSeconds": 60,
        "maxRuns": 100
      }
    ],
    "rules": [
      {
        "id": "low-balance-alert",
        "when": [
          {"metric": "balance_lamports", "op": "lt", "value": 1000000}
        ],
        "then": {
          "type": "query_balance",
          "protocol": "system-program",
          "intent": {}
        },
        "cooldownSeconds": 300
      }
    ]
  }
}

Show Autonomy Fields

boolean

default:false

Enable autonomous execution

enum

default:"execute"

execute (real) or paper (simulation)

number

default:30

Heartbeat interval (1-86400)

number

default:60

Maximum actions per hour (1-3600)

array

Array of scheduled execution steps

array

Array of condition-based decision rules

List Agents

List all agents.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/agents

Get Agent

Retrieve agent details.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000

Path Parameters

string

required

Agent UUID

Update Agent Capabilities

Update agent’s allowed intents and execution mode.

cURL

curl -X PUT \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIntents": ["transfer_sol", "swap", "stake", "query_balance"],
    "executionMode": "supervised",
    "budgetLamports": 200000000
  }' \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/capabilities

Path Parameters

string

required

Agent UUID

Request Body

array

required

Updated array of allowed transaction types

enum

autonomous or supervised

object

Updated autonomy configuration

number

Updated budget

Start Agent

Start a stopped agent.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/start

Path Parameters

string

required

Agent UUID

Stop Agent

Stop a running agent.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/stop

Path Parameters

string

required

Agent UUID

Pause Agent

Pause a running agent with optional reason.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Manual review required"}' \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/pause

Path Parameters

string

required

Agent UUID

Request Body

string

Reason for pausing

Resume Agent

Resume a paused agent.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/resume

Path Parameters

string

required

Agent UUID

Get Agent Budget

Retrieve agent budget and spending information.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/budget

Path Parameters

string

required

Agent UUID

Response

string

required

Agent UUID

string

required

Wallet UUID

number

required

Total budget in lamports

number

required

Amount spent in current 24-hour period

string

required

ISO 8601 timestamp

{
  "status": "success",
  "data": {
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "budgetLamports": 100000000,
    "spentLamportsToday": 5000000,
    "updatedAt": "2026-03-08T12:00:00.000Z"
  }
}

Get Autonomy State

Retrieve current autonomous execution state.

cURL

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/autonomy/state

Path Parameters

string

required

Agent UUID

Issue Capability Manifest

Issue a signed capability manifest for an agent.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIntents": ["transfer_sol", "swap"],
    "allowedProtocols": ["system-program", "jupiter"],
    "ttlSeconds": 3600
  }' \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/manifest/issue

Path Parameters

string

required

Agent UUID

Request Body

array

required

Array of transaction types the manifest allows

array

required

Array of protocols the manifest allows

number

default:3600

Manifest validity duration in seconds (max: 2,592,000 / 30 days)

Response

string

required

Manifest issuer identifier

string

required

Manifest version

string

required

Agent UUID

array

required

Allowed transaction types

array

required

Allowed protocols

string

required

ISO 8601 timestamp

string

required

ISO 8601 timestamp

string

required

Unique nonce

string

required

Manifest signature

Verify Capability Manifest

Verify a capability manifest signature and validity.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "manifest": {
      "issuer": "agentic-wallet-runtime",
      "version": "1.0.0",
      "agentId": "123e4567-e89b-12d3-a456-426614174000",
      "allowedIntents": ["transfer_sol"],
      "allowedProtocols": ["system-program"],
      "issuedAt": "2026-03-08T12:00:00.000Z",
      "expiresAt": "2026-03-08T13:00:00.000Z",
      "nonce": "abc123def456",
      "signature": "sig..."
    }
  }' \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/manifest/verify

Path Parameters

string

required

Agent UUID

Request Body

object

required

Complete capability manifest object

Response

{
  "status": "success",
  "data": {
    "valid": true,
    "reason": "Manifest is valid and not expired"
  }
}

Execute Agent Intent

Execute a transaction intent on behalf of an agent.

cURL

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transfer_sol",
    "protocol": "system-program",
    "intent": {
      "destination": "7xKLvUhXW9XqHZzN3Jw8wVHGK6R4tN2gqV9mP3kL5eXy",
      "lamports": 1000000
    },
    "gasless": false
  }' \
  http://localhost:3000/api/v1/agents/123e4567-e89b-12d3-a456-426614174000/execute

Path Parameters

string

required

Agent UUID

Request Body

enum

required

Transaction type (must be in agent’s allowedIntents)

string

required

Protocol name

object

default:"{}"

Protocol-specific intent payload

boolean

default:false

Use gasless submission if supported

Response

Returns a transaction object (same as POST /api/v1/transactions).

This endpoint enforces agent capabilities, budget limits, and policy rules.

Agent Execution Modes

Autonomous
Supervised

Autonomous ModeAgent executes based on configured rules and steps without manual intervention.Features:

Scheduled steps with cooldown periods
Conditional decision rules
Rate limiting (maxActionsPerHour)
Budget enforcement
Policy evaluation
Execute or paper mode

Use Cases:

Automated trading bots
Rebalancing agents
Liquidity providers
Monitoring agents

Treasury Operations

See Treasury API for agent budget allocation and rebalancing.

Strategy Operations

Backtest and paper trading for agents:

Backtest Strategy

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Test Strategy",
    "minimumPassRate": 0.7,
    "steps": [
      {
        "type": "query_balance",
        "protocol": "system-program",
        "intent": {},
        "timestamp": "2026-03-08T12:00:00.000Z"
      }
    ]
  }' \
  http://localhost:3000/api/v1/strategy/backtest

Execute Paper Trade

curl -X POST \
  -H "x-api-key: dev-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "swap",
    "protocol": "jupiter",
    "intent": {
      "inputMint": "So11111111111111111111111111111111111111112",
      "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "1000000",
      "slippageBps": 50
    }
  }' \
  http://localhost:3000/api/v1/strategy/paper/execute

List Paper Trades

curl -H "x-api-key: dev-api-key" \
     http://localhost:3000/api/v1/strategy/paper/123e4567-e89b-12d3-a456-426614174000

​Create Agent

​Request Body

​Response

​Autonomy Configuration

​List Agents

​Get Agent

​Path Parameters

​Update Agent Capabilities

​Path Parameters

​Request Body

​Start Agent

​Path Parameters

​Stop Agent

​Path Parameters

​Pause Agent

​Path Parameters

​Request Body

​Resume Agent

​Path Parameters

​Get Agent Budget

​Path Parameters

​Response

​Get Autonomy State

​Path Parameters

​Issue Capability Manifest

​Path Parameters

​Request Body

​Response

​Verify Capability Manifest

​Path Parameters

​Request Body

​Response

​Execute Agent Intent

​Path Parameters

​Request Body

​Response

​Agent Execution Modes

​Treasury Operations

​Strategy Operations

​Backtest Strategy

​Execute Paper Trade

​List Paper Trades

Create Agent

Request Body

Response

Autonomy Configuration

List Agents

Get Agent

Path Parameters

Update Agent Capabilities

Path Parameters

Request Body

Start Agent

Path Parameters

Stop Agent

Path Parameters

Pause Agent

Path Parameters

Request Body

Resume Agent

Path Parameters

Get Agent Budget

Path Parameters

Response

Get Autonomy State

Path Parameters

Issue Capability Manifest

Path Parameters

Request Body

Response

Verify Capability Manifest

Path Parameters

Request Body

Response

Execute Agent Intent

Path Parameters

Request Body

Response

Agent Execution Modes

Treasury Operations

Strategy Operations

Backtest Strategy

Execute Paper Trade

List Paper Trades