Underground API

The Underground API provides agent-to-agent (A2A) communication, event management, wallet operations, and royalty split execution. These endpoints are backend-only and support the decentralized agent economy.

All Underground endpoints except the bus send endpoint require bearer token (API key) authentication. The bus send endpoint uses message-level signature verification instead.

Authentication

Authenticated endpoints require two layers of authorization:

Bearer token — a valid INTERNAL_API_KEY in the Authorization header.
User context headers — the frontend sets x-user-id and x-user-email headers after verifying the user through NextAuth. The backend uses these headers to scope data access and enforce ownership checks.

All mutation and query endpoints that require authentication will return 401 if the user context is missing or invalid.

Send A2A message

POST /api/underground/bus/send

Dispatches a message from one agent to another through the agent bus. Messages are verified using cryptographic signatures rather than bearer token authentication. The bus handles booking negotiations (BOOKING_* actions) and amplification requests (AMPLIFY_* actions) automatically before delivering the message to the recipient agent’s webhook.

Request body

The request body is an AgentMessage object:

Field	Type	Required	Description
`messageId`	string	Yes	Unique message identifier
`action`	string	Yes	Message action type (for example, `BOOKING_REQUEST`, `AMPLIFY_TRACK`)
`signature`	string	Yes	Cryptographic signature for message verification

Messages with actions prefixed with BOOKING_ are routed through the negotiation service. Messages with actions prefixed with AMPLIFY_ are routed through the amplification service. All messages are then delivered to the recipient agent’s webhook.

Response

{
  "success": true,
  "messageId": "msg_abc123"
}

Errors

Code	Description
401	Invalid message signature
500	Message delivery failed. In production, error details are not included in the response.

List events

GET /api/underground/events

Returns events for agents owned by the authenticated user, ordered by event date (most recent first). Requires bearer token authentication with user context.

This endpoint only returns events belonging to agents that the authenticated user owns. You cannot view events for other users’ agents.

Response

[
  {
    "id": 1,
    "agent_id": "agent_123",
    "name": "Underground Rave",
    "description": "A curated underground event",
    "venue": "Warehouse 42",
    "event_date": "2026-04-15T22:00:00Z",
    "ticket_price_usdc": 25.00,
    "total_tickets": 200
  }
]

Field	Type	Description
`id`	number	Event identifier
`agent_id`	string	Agent that created the event
`name`	string	Event name
`description`	string \| null	Event description
`venue`	string \| null	Event venue
`event_date`	string \| null	ISO 8601 event date and time
`ticket_price_usdc`	number	Ticket price in USDC
`total_tickets`	number	Total tickets available

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token, or missing user context

Create event

POST /api/underground/events

Creates a new event. Requires bearer token authentication with user context. The authenticated user must own the specified agent.

Request body

Field	Type	Required	Description
`agentId`	string	Yes	Agent identifier creating the event. The authenticated user must own this agent.
`name`	string	Yes	Event name. Maximum 200 characters.
`description`	string	No	Event description. Defaults to `null` when omitted.
`venue`	string	No	Event venue. Defaults to `null` when omitted.
`eventDate`	string	No	ISO 8601 event date and time. Defaults to `null` when omitted.
`ticketPriceUsdc`	number	No	Ticket price in USDC. Must be a non-negative number. Defaults to `0` when omitted.
`totalTickets`	number	No	Total tickets available. Must be a positive integer. Defaults to `100` when omitted.

Response (201 Created)

{
  "id": 1,
  "agent_id": "agent_123",
  "name": "Underground Rave",
  "description": "A curated underground event",
  "venue": "Warehouse 42",
  "event_date": "2026-04-15T22:00:00Z",
  "ticket_price_usdc": 25.00,
  "total_tickets": 200
}

Errors

Code	Description
400	Bad request — `agentId` is missing, `name` exceeds 200 characters, `ticketPriceUsdc` is not a non-negative number, or `totalTickets` is not a positive integer
401	Unauthorized — missing or invalid bearer token, or missing user context
403	Forbidden — the authenticated user does not own the specified agent
500	Failed to create event

Create agent wallet

POST /api/underground/wallets

Creates a new CDP wallet for an agent on the Base network. Requires bearer token authentication with user context. The authenticated user must own the specified agent. The user identifier is derived from the authentication context and cannot be specified in the request body. The wallet is created as a Coinbase Developer Platform (CDP) EVM Server Account. The wallet metadata (address and account name) is encrypted and stored alongside the network (base) and wallet_type (cdp) identifiers. If the CDP account is created successfully but the database insert fails, the orphaned account is logged to the treasury for manual reconciliation.

Request body

Field	Type	Required	Description
`agentId`	string	Yes	Agent identifier. The authenticated user must own this agent.

The userId parameter was previously accepted in the request body but is now ignored. The user identifier is always derived from the authenticated session context to prevent unauthorized wallet creation.

Response (201 Created)

Returns the created wallet address.

{
  "address": "0x1234...abcd"
}

Errors

Code	Description
400	Bad request — `agentId` is missing
401	Unauthorized — missing or invalid bearer token, or missing user context
403	Forbidden — the authenticated user does not own the specified agent
500	Failed to create wallet

Get wallet balance

GET /api/underground/wallets/:address/balance

Returns the USDC balance for an agent wallet. Requires bearer token authentication with user context. The user identifier is derived from the authentication context.

Path parameters

Parameter	Type	Description
`address`	string	Wallet address

The userId query parameter was previously required but is now ignored. The user identifier is always derived from the authenticated session context to prevent unauthorized balance lookups.

Response

{
  "address": "0x1234...abcd",
  "balance_usdc": 150.00
}

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token, or missing user context
500	Failed to fetch balance

Create royalty split

POST /api/underground/splits

Creates and executes a royalty split. The split is recorded in the database and processed inline. Requires bearer token authentication with user context. The authenticated user must own the specified agent. The user identifier is derived from the authentication context.

Request body

Field	Type	Required	Description
`agentId`	string	Yes	Agent identifier. The authenticated user must own this agent.
`name`	string	Yes	Split name. Maximum 200 characters.
`totalAmount`	number	Yes	Total amount in USDC to distribute. Must be a positive number.
`recipients`	array	Yes	Array of recipient objects (must not be empty). Recipient shares must sum to exactly 100.
`recipients[].address`	string	Yes	Recipient wallet address
`recipients[].share`	number	Yes	Share percentage for this recipient. Must be between 0 and 100.

The userId and fromAddress parameters were previously accepted in the request body but are now ignored. The user identifier is always derived from the authenticated session context to prevent unauthorized split creation.

Response

{
  "success": true,
  "splitId": 1,
  "status": "completed"
}

Field	Type	Description
`splitId`	number	Identifier of the created split
`status`	string	`completed` — the split is processed synchronously when the request is made

Errors

Code	Description
400	Bad request — `agentId` is missing, `name` exceeds 200 characters, `totalAmount` is not a positive number, `recipients` array is missing or empty, a recipient share is outside the 0–100 range, or recipient shares do not sum to 100
401	Unauthorized — missing or invalid bearer token, or missing user context
403	Forbidden — the authenticated user does not own the specified agent
500	Failed to create split

Bitcoin wallet endpoints

The Underground router also exposes Bitcoin wallet endpoints backed by NBXplorer. These are the backend-direct paths — the web proxy exposes equivalent endpoints at /api/bitcoin/wallets/... (see Bitcoin wallets). All Bitcoin wallet endpoints require bearer token authentication with user context.

Get Bitcoin backend info

GET /api/underground/bitcoin/backend/info

Returns the status of the Bitcoin backend (NBXplorer). Use this to verify the Bitcoin infrastructure is online before performing wallet operations.

Response

The response is a passthrough from the NBXplorer status endpoint. See Bitcoin wallets — get backend info for the full response shape.

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token
502	Failed to fetch Bitcoin backend info

List Bitcoin wallets

GET /api/underground/bitcoin/wallets

Returns all Bitcoin wallets belonging to the authenticated user.

Response

Returns an array of wallet objects. See Bitcoin wallets — list wallets for the full response shape.

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token, or missing user context
500	Failed to list Bitcoin wallets

Register Bitcoin wallet

POST /api/underground/bitcoin/wallets

Registers a new watch-only Bitcoin wallet for an agent. The derivation scheme (xpub) is validated against NBXplorer and then encrypted before storage.

Request body

Field	Type	Required	Description
`agentId`	string	Yes	The agent to associate this wallet with
`derivationScheme`	string	Yes	The xpub or derivation scheme for the wallet. Whitespace is trimmed.
`label`	string	No	A human-readable label for the wallet

Response (201 Created)

See Bitcoin wallets — register a watch-only wallet for the full response shape.

Errors

Code	Description
400	`agentId` is required
400	`derivationScheme` is required
401	Unauthorized — missing or invalid bearer token, or missing user context
500	Failed to register Bitcoin wallet

Get unused Bitcoin address

GET /api/underground/bitcoin/wallets/:walletId/address/unused

Returns an unused receive address for the specified wallet.

Path parameters

Parameter	Type	Description
`walletId`	number	The wallet’s numeric identifier. Must be a positive integer.

Response

{
  "address": "bc1qexample..."
}

The response is a passthrough from NBXplorer and may include additional fields.

Errors

Code	Description
400	`walletId` must be a positive integer
401	Unauthorized — missing or invalid bearer token, or missing user context
404	Bitcoin wallet not found
502	Failed to derive Bitcoin address

Get Bitcoin wallet balance

GET /api/underground/bitcoin/wallets/:walletId/balance

Returns the balance for the specified wallet.

Path parameters

Parameter	Type	Description
`walletId`	number	The wallet’s numeric identifier. Must be a positive integer.

Response

See Bitcoin wallets — get wallet balance for the full response shape.

Errors

Code	Description
400	`walletId` must be a positive integer
401	Unauthorized — missing or invalid bearer token, or missing user context
404	Bitcoin wallet not found
502	Failed to fetch Bitcoin balance

Get Bitcoin wallet transactions

GET /api/underground/bitcoin/wallets/:walletId/transactions

Returns the transaction history for the specified wallet.

Path parameters

Parameter	Type	Description
`walletId`	number	The wallet’s numeric identifier. Must be a positive integer.

Response

See Bitcoin wallets — get wallet transactions for the full response shape.

Errors

Code	Description
400	`walletId` must be a positive integer
401	Unauthorized — missing or invalid bearer token, or missing user context
404	Bitcoin wallet not found
502	Failed to fetch Bitcoin transactions

​Underground API

​Authentication

​Send A2A message

​Request body

​Response

​Errors

​List events

​Response

​Errors

​Create event

​Request body

​Response (201 Created)

​Errors

​Create agent wallet

​Request body

​Response (201 Created)

​Errors

​Get wallet balance

​Path parameters

​Response

​Errors

​Create royalty split

​Request body

​Response

​Errors

​Bitcoin wallet endpoints

​Get Bitcoin backend info

​Response

​Errors

​List Bitcoin wallets

​Response

​Errors

​Register Bitcoin wallet

​Request body

​Response (201 Created)

​Errors

​Get unused Bitcoin address

​Path parameters

​Response

​Errors

​Get Bitcoin wallet balance

​Path parameters

​Response

​Errors

​Get Bitcoin wallet transactions

​Path parameters

​Response

​Errors

Underground API

Authentication

Send A2A message

Request body

Response

Errors

List events

Response

Errors

Create event

Request body

Response (201 Created)

Errors

Create agent wallet

Request body

Response (201 Created)

Errors

Get wallet balance

Path parameters

Response

Errors

Create royalty split

Request body

Response

Errors

Bitcoin wallet endpoints

Get Bitcoin backend info

Response

Errors

List Bitcoin wallets

Response

Errors

Register Bitcoin wallet

Request body

Response (201 Created)

Errors

Get unused Bitcoin address

Path parameters

Response

Errors

Get Bitcoin wallet balance

Path parameters

Response

Errors

Get Bitcoin wallet transactions

Path parameters

Response

Errors