Using Nova Tools with AI Agents

Nova's tools are available to AI agents via the Model Context Protocol (MCP) and a standard REST API with x402 inline payments on Stacks mainnet.

Nova2 min readMarkdown

In short

Explains how AI agents connect to Nova Tools over MCP or REST, discover tools, which callers pay per call with x402, and the rate limits for identified and anonymous agents.

Connecting

Option 1: MCP Server (Recommended)

Install the Nova MCP server to give your agent native tool access:

npx @nova/mcp-server

Or connect directly via Streamable HTTP:

https://nova.zeroauthoritydao.com/mcp

Environment variables (optional):

Variable	Default	Description
`NOVA_API_URL`	`https://nova.zeroauthoritydao.com`	Nova API base URL
`AGENT_STACKS_ADDRESS`	—	Your Stacks address, sent as identity for the higher agent rate limits

Option 2: REST API (Direct)

Call tool endpoints directly with standard HTTP:

curl -X POST https://nova.zeroauthoritydao.com/api/tools/stacks-token-analytics/run \
  -H "Content-Type: application/json" \
  -d '{"input": {"token": "WELSH"}}'

Paid tools return HTTP 402 with payment requirements — the x402 Payment Guide covers how to complete payment and retry.

Tool Discovery

The full catalog (50+ tools across Stacks, Bitcoin, EVM, Solana, TON, Sui, Aptos, Hyperliquid, and community ecosystems) is in the Tools catalog. Machine-readable listings:

Endpoint	What it returns
`GET /api/tools`	Tool list with slugs, input schemas, and pricing
`GET /.well-known/agent.json`	Agent manifest: tools, schemas, payment options, MCP endpoint info
`GET /api/tools/openapi.json`	OpenAPI spec
`GET /llms.txt`	llms.txt index

Over MCP, call tools/list — every tool is auto-discovered with full input schemas and pricing.

Payment Model

Caller Type	Paid Tools	Free Tools
Nova Premium (JWT)	Free within the monthly included-calls limit	Free, unlimited
Identified agent (Stacks address)	x402 payment per call	Free, rate-limited
Anonymous (IP only)	x402 payment per call	Free, stricter rate limits

Payment mechanics — headers, the 402 flow, accepted tokens, errors, and the verify → execute → settle safety guarantee — live in the x402 Payment Guide.

Rate Limits

Caller Type	Limit
Identified agent (x402 / wallet-identified)	10 req/min, 240 req/hour
Anonymous (per IP)	5 req/min, 120 req/hour

Exceeding limits returns 429 Too Many Requests (never 402). Include your Stacks address (AGENT_STACKS_ADDRESS / X-STACKS-ADDRESS) to get the higher agent limits.

Example: Full Agent Flow

Discover tools: GET /.well-known/agent.json
Call a tool: POST /api/tools/stacks-token-analytics/run with {"input": {"token": "WELSH"}}
Receive 402: parse the payment-required header for payment options
Sign payment and retry with the payment-signature header (details)
Receive results: tool output in the body, settlement receipt in the payment-response header