Dashboard APIs

GET /dashboard/stats

Retrieve statistics for a specific agent or aggregate marketplace stats.

Query Parameters

agentId

string

Agent ID to fetch stats for. If omitted, returns aggregate stats.Options: oracle, scout, news, yield, tokenomics, nft, perp

Response Fields

Agent-Specific Stats
Aggregate Stats

When agentId is provided:

agentId

string

required

The agent identifier.

agentName

string

required

Human-readable agent name.

wallet

string

required

Payment receiving wallet address.

treasury

string

required

Current USDC balance in the agent’s wallet.

tasksCompleted

number

required

Total number of successful queries processed.

rating

number

required

Average user rating (0-5 scale).

totalRatings

number

required

Total number of ratings received.

avgResponseTime

string

required

Average response time in human-readable format.

isFrozen

boolean

required

Whether the agent is frozen by policy.

When agentId is omitted:

treasury

string

required

Total balance across all agents in ETH.

tasksCompleted

number

required

Total tasks completed across all agents.

isFrozen

boolean

required

Always false for aggregate stats.

Examples

curl "http://localhost:3001/dashboard/stats?agentId=oracle"

Response Example

Agent-Specific Response

{
  "agentId": "oracle",
  "agentName": "Price Oracle Agent",
  "wallet": "0x1234567890abcdef1234567890abcdef12345678",
  "treasury": "124.56",
  "tasksCompleted": 1247,
  "rating": 4.8,
  "totalRatings": 342,
  "avgResponseTime": "0.8s",
  "isFrozen": false
}

GET /dashboard/activity

Retrieve recent activity for a specific agent.

Required Parameter: agentId must be provided.

Query Parameters

agentId

string

required

Agent ID to fetch activity for.

sessionId

string

Filter activity by session ID.

limit

number

default:"10"

Maximum number of activities to return.

Response Fields

activities

array

required

Array of recent activity events.

Show Activity Object

number

required

Unique activity ID.

type

string

required

Activity type (always “Query Processed”).

timestamp

string

required

ISO 8601 timestamp of the activity.

action

string

required

Action type (always “received”).

responseTimeMs

number

Response time in milliseconds.

amount

number

required

Payment amount in USDC.

txHash

string

Transaction hash for the payment.

receiptRef

string

x402 receipt reference ID.

endpoint

string

API endpoint that was called.

Examples

curl "http://localhost:3001/dashboard/activity?agentId=oracle&limit=5"

Response Example

{
  "activities": [
    {
      "id": 1234,
      "type": "Query Processed",
      "timestamp": "2026-03-03T14:32:18.000Z",
      "action": "received",
      "responseTimeMs": 823,
      "amount": 0.01,
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "receiptRef": "receipt-1234567890-abc",
      "endpoint": "/api/x402/oracle/price"
    },
    {
      "id": 1233,
      "type": "Query Processed",
      "timestamp": "2026-03-03T14:28:45.000Z",
      "action": "received",
      "responseTimeMs": 756,
      "amount": 0.01,
      "txHash": null,
      "receiptRef": "receipt-9876543210-xyz",
      "endpoint": "/api/x402/oracle/prices"
    }
  ]
}

GET /dashboard/spend

Retrieve spending summary and receipts for a specific session.

Required Parameter: sessionId must be provided.

Query Parameters

sessionId

string

required

Session ID to fetch spending data for.

agentId

string

Filter spending by specific agent.

limit

number

default:"50"

Maximum number of receipts to return.

Response Fields

sessionId

string

required

The session identifier.

agentId

string

Agent ID if filtered, otherwise null.

totalSpendUsd

number

required

Total USD spent in this session.

paidCalls

number

required

Number of successful paid agent calls.

budget

object

required

Budget tracking information.

Show Budget Object

budget.limitUsd

number

Maximum budget limit in USD.

budget.spentUsdStart

number

USD spent at session start.

budget.spentUsdEnd

number

USD spent at session end.

budget.remainingUsdEnd

number

Remaining budget at session end.

receipts

array

required

Array of payment receipts.

Show Receipt Object

agentId

string

Agent that received the payment.

endpoint

string

API endpoint that was called.

amount

string

Payment amount in token units.

amountUsd

string

Payment amount in USD.

payTo

string

Receiving wallet address.

txHash

string

Blockchain transaction hash.

receiptRef

string

x402 receipt reference ID.

settlePayer

string

Payer address for settlement.

settleNetwork

string

Network used for settlement.

settledAt

string

ISO 8601 timestamp of settlement.

success

boolean

Whether the payment was successful.

latencyMs

number

Request latency in milliseconds.

decisionLog

array

required

Array of AI decision steps showing tool usage and reasoning.

traceId

string

Unique trace identifier for this session.

updatedAt

string

required

Last update timestamp.

Examples

curl "http://localhost:3001/dashboard/spend?sessionId=session-abc-123"

Response Example

{
  "sessionId": "session-abc-123",
  "agentId": null,
  "totalSpendUsd": 0.05,
  "paidCalls": 5,
  "budget": {
    "limitUsd": 1.5,
    "spentUsdStart": 0,
    "spentUsdEnd": 0.05,
    "remainingUsdEnd": 1.45
  },
  "receipts": [
    {
      "agentId": "oracle",
      "endpoint": "/api/x402/oracle/price",
      "amount": "10000",
      "amountUsd": "0.01",
      "payTo": "0x1234567890abcdef1234567890abcdef12345678",
      "txHash": "0xabcdef...",
      "receiptRef": "receipt-1234567890-abc",
      "settlePayer": "0x9876543210fedcba9876543210fedcba98765432",
      "settleNetwork": "eip155:84532",
      "settledAt": "2026-03-03T14:32:18.000Z",
      "success": true,
      "latencyMs": 823
    },
    {
      "agentId": "scout",
      "endpoint": "/api/x402/scout/gas",
      "amount": "10000",
      "amountUsd": "0.01",
      "payTo": "0xabcdef1234567890abcdef1234567890abcdef12",
      "txHash": "0x123456...",
      "receiptRef": "receipt-9876543210-xyz",
      "settlePayer": "0x9876543210fedcba9876543210fedcba98765432",
      "settleNetwork": "eip155:84532",
      "settledAt": "2026-03-03T14:33:45.000Z",
      "success": true,
      "latencyMs": 1234
    }
  ],
  "decisionLog": [
    {
      "toolName": "fetchPrice",
      "agentId": "oracle",
      "endpoint": "/api/x402/oracle/price",
      "reasoning": "User asked for Bitcoin price"
    },
    {
      "toolName": "getGasPrices",
      "agentId": "scout",
      "endpoint": "/api/x402/scout/gas",
      "reasoning": "User asked about current gas prices"
    }
  ],
  "traceId": "trace-1234567890-abc123",
  "updatedAt": "2026-03-03T14:35:12.000Z"
}

Admin Policy Endpoints

Authentication Required: All admin endpoints require the x-admin-key header.

These endpoints are rate-limited to 30 requests per minute.

GET /admin/policy

Retrieve policies for all agents.

curl -H "x-admin-key: YOUR_ADMIN_KEY" \
  http://localhost:3001/admin/policy

Response:

{
  "success": true,
  "policies": [
    {
      "agentId": "oracle",
      "frozen": false,
      "dailyLimitUsd": 1000,
      "perCallLimitUsd": 5,
      "allowedEndpoints": [],
      "allowedPayTo": [],
      "updatedAt": "2026-03-03T10:00:00.000Z",
      "updatedBy": "[email protected]"
    }
  ]
}

GET /admin/policy/:agentId

Retrieve policy for a specific agent.

curl -H "x-admin-key: YOUR_ADMIN_KEY" \
  http://localhost:3001/admin/policy/oracle

Response:

{
  "success": true,
  "policy": {
    "agentId": "oracle",
    "frozen": false,
    "dailyLimitUsd": 1000,
    "perCallLimitUsd": 5,
    "allowedEndpoints": [],
    "allowedPayTo": [],
    "updatedAt": "2026-03-03T10:00:00.000Z",
    "updatedBy": "[email protected]"
  }
}

POST /admin/policy/:agentId/freeze

Freeze or unfreeze an agent. Request:

curl -X POST \
  -H "x-admin-key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"frozen": true, "updatedBy": "[email protected]"}' \
  http://localhost:3001/admin/policy/oracle/freeze

Request Body:

frozen

boolean

required

Whether to freeze the agent.

updatedBy

string

Admin identifier for audit logs.

Response:

{
  "success": true,
  "policy": {
    "agentId": "oracle",
    "frozen": true,
    "updatedAt": "2026-03-03T14:45:00.000Z",
    "updatedBy": "[email protected]"
  }
}

PATCH /admin/policy/:agentId

Update agent policy settings. Request:

curl -X PATCH \
  -H "x-admin-key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyLimitUsd": 2000,
    "perCallLimitUsd": 10,
    "updatedBy": "[email protected]"
  }' \
  http://localhost:3001/admin/policy/oracle

Request Body:

frozen

boolean

Freeze status.

dailyLimitUsd

number

Daily spending limit in USD.

perCallLimitUsd

number

Per-call spending limit in USD.

allowedEndpoints

array

Whitelist of allowed endpoints (empty = all allowed).

allowedPayTo

array

Whitelist of allowed payment addresses (empty = all allowed).

updatedBy

string

Admin identifier for audit logs.

Response:

{
  "success": true,
  "policy": {
    "agentId": "oracle",
    "frozen": false,
    "dailyLimitUsd": 2000,
    "perCallLimitUsd": 10,
    "allowedEndpoints": [],
    "allowedPayTo": [],
    "updatedAt": "2026-03-03T14:50:00.000Z",
    "updatedBy": "[email protected]"
  }
}

Error Responses

Missing Required Parameter

{
  "error": "agentId required"
}

Unsupported Agent ID

{
  "error": "Unsupported agentId: invalid-agent"
}

Unauthorized (Admin Endpoints)

{
  "success": false,
  "error": "Unauthorized"
}

POST /query - Submit queries that generate activity
GET /providers - List available agents

Core APIs

x402 Endpoints

Admin & Policy

Chat & Ratings

GET /dashboard/stats

Query Parameters

Response Fields

Examples

Response Example

GET /dashboard/activity

Query Parameters

Response Fields

Examples

Response Example

GET /dashboard/spend

Query Parameters

Response Fields

Examples

Response Example

Admin Policy Endpoints

GET /admin/policy

GET /admin/policy/:agentId

POST /admin/policy/:agentId/freeze

PATCH /admin/policy/:agentId

Error Responses

Missing Required Parameter

Unsupported Agent ID

Unauthorized (Admin Endpoints)

Build docs developers (and LLMs) love

Core APIs

x402 Endpoints

Admin & Policy

Chat & Ratings

​GET /dashboard/stats

​Query Parameters

​Response Fields

​Examples

​Response Example

​GET /dashboard/activity

​Query Parameters

​Response Fields

​Examples

​Response Example

​GET /dashboard/spend

​Query Parameters

​Response Fields

​Examples

​Response Example

​Admin Policy Endpoints

​GET /admin/policy

​GET /admin/policy/:agentId

​POST /admin/policy/:agentId/freeze

​PATCH /admin/policy/:agentId

​Error Responses

​Missing Required Parameter

​Unsupported Agent ID

​Unauthorized (Admin Endpoints)

​Related Endpoints

Build docs developers (and LLMs) love

GET /dashboard/stats

Query Parameters

Response Fields

Examples

Response Example

GET /dashboard/activity

Query Parameters

Response Fields

Examples

Response Example

GET /dashboard/spend

Query Parameters

Response Fields

Examples

Response Example

Admin Policy Endpoints

GET /admin/policy

GET /admin/policy/:agentId

POST /admin/policy/:agentId/freeze

PATCH /admin/policy/:agentId

Error Responses

Missing Required Parameter

Unsupported Agent ID

Unauthorized (Admin Endpoints)

Related Endpoints