# Using Nova Tools with AI Agents

{% hint style="info" %}
Nova tools use the x402 payment protocol. Agents pay per request using STX, sBTC, or USDCx — no API keys, no subscriptions, no registration required.
{% endhint %}

***

### Quick Start

#### Option 1: MCP Server (Recommended)

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

```bash
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 for free quota tracking |

#### Option 2: REST API (Direct)

Call tool endpoints directly with standard HTTP:

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

This returns **HTTP 402** with payment requirements. See the x402 Payment Guide for how to complete payment and retry.

***

### Tool Discovery

#### Agent Manifest

Machine-readable tool listing at:

```
https://nova.zeroauthoritydao.com/.well-known/agent.json
```

Returns all available tools with input schemas, pricing, payment options, and MCP endpoint info.

#### MCP tools/list

Connect to the MCP endpoint and call `tools/list` to discover available tools programmatically.

***

### Available Tools

| Tool                 | Slug              | Price    | Description                                                                                                  |
| -------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| Deep Token Analytics | `token-analytics` | 500 sats | Real-time price, market data, holder distribution, trading volume, and on-chain metrics for any Stacks token |

More tools coming soon: Contract Scanner, Portfolio Tracker, NFT Collection Analytics.

***

### Payment Model

| Caller Type                           | Paid Tools            | Free Tools                                    |
| ------------------------------------- | --------------------- | --------------------------------------------- |
| **Nova Premium** (JWT)                | Free, unlimited       | Free, unlimited                               |
| **Identified agent** (Stacks address) | x402 payment per call | 10 free calls/day, then x402 at reduced price |
| **Anonymous**                         | x402 payment per call | Must provide identity (Stacks address)        |

**Accepted tokens**: STX, sBTC, USDCx — all on Stacks mainnet.

**Free quota**: 10 calls/day across all free tools, tracked by Stacks address. Include `X-STACKS-ADDRESS` header to use quota.

{% hint style="success" %}
x402 uses a two-phase flow: **verify, execute, then settle**. If tool execution fails, your wallet is never charged.
{% endhint %}

***

### Rate Limits

| Caller Type                                                       | Limit                   |
| ----------------------------------------------------------------- | ----------------------- |
| Agent (per Stacks address)                                        | 10 req/min, 60 req/hour |
| Discovery endpoints (`GET /api/tools`, `/.well-known/agent.json`) | 120/hour per IP         |

Exceeding limits returns **429 Too Many Requests** (never 402).

***

### Example: Full Agent Flow

1. **Discover tools**: `GET /.well-known/agent.json`
2. **Call a tool**: `POST /api/tools/token-analytics/run` with `{"input": {"token": "WELSH"}}`
3. **Receive 402**: Parse `payment-required` header for payment options
4. **Sign payment**: Build a Stacks transaction with `sponsored: true, fee: 0`
5. **Retry with payment**: Same request + `payment-signature` header
6. **Receive results**: Tool output in response body, settlement receipt in `payment-response` header

***

### Get Unlimited Access

Skip payments entirely with [Nova Premium](https://nova.zeroauthoritydao.com/premium). All tools are included at no per-call cost.