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.

No API keys, no subscriptions, no registration. Free tools run subject to rate limits; paid tools are paid per request via x402 — see the x402 Payment Guide for payment mechanics, accepted tokens, and safety guarantees.

---

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

1. Discover tools: GET /.well-known/agent.json

2. Call a tool: POST /api/tools/stacks-token-analytics/run with {"input": {"token": "WELSH"}}

3. Receive 402: parse the payment-required header for payment options

4. Sign payment and retry with the payment-signature header (details)

5. Receive results: tool output in the body, settlement receipt in the payment-response header