Agent Integration Guide
Everything an agent — or the person wiring one up — needs to discover, connect to, and pay Cabrini. Human-friendly product pages live on the homepage; this page is the technical source of truth.
Discovery endpoints
Cabrini describes itself over every major agent discovery standard. All of these are free:
Connect over MCP
Cabrini runs a streamable-HTTP MCP server at https://cabrini.ai/mcp. For Claude Code:
claude mcp add --transport http cabrini https://cabrini.ai/mcp
Or in any MCP client config that supports HTTP transports:
{
"mcpServers": {
"cabrini": {
"type": "http",
"url": "https://cabrini.ai/mcp"
}
}
}
MCP tools
| Tool | Arguments | Price |
|---|
query_minute_bars | ticker, date | $0.025 |
list_tickers | date | $0.005 |
query_range | ticker, start, end | $0.01/day, max 20 |
query_batch | tickers[], date | $0.02/ticker, max 25 |
get_pricing | — | free |
get_stats | — | free |
Paid tools respond over MCP with structured payment instructions (endpoint, price, protocol). The agent completes the x402 payment over plain HTTP and retries — MCP for discovery and orchestration, HTTP for settlement.
Pay with x402
x402 v2, USDC on Base (eip155:84532 — Sepolia testnet today, mainnet soon). The full cycle:
# 1. Request without payment
POST https://cabrini.ai/v1/query
{"ticker": "AAPL", "date": "2024-01-15"}
# 2. 402 response carries base64 payment terms
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6...
# 3. Decode → {amount, receiver, network, asset}
# 4. Sign USDC transfer for the exact amount
# 5. Retry with proof
POST https://cabrini.ai/v1/query
PAYMENT-SIGNATURE: <signed-payload>
{"ticker": "AAPL", "date": "2024-01-15"}
# 6. Data + receipt
HTTP/1.1 200 OK
PAYMENT-RESPONSE: <settlement-receipt>
Python example
# pip install x402 httpx eth-account
from x402.clients.httpx import x402HttpxClient
from eth_account import Account
account = Account.from_key("0x...") # agent's wallet
async with x402HttpxClient(account=account, base_url="https://cabrini.ai") as client:
r = await client.post("/v1/query", json={"ticker": "AAPL", "date": "2024-01-15"})
bars = r.json()["data"] # payment handled automatically
TypeScript example
// npm install x402-fetch viem
import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount("0x...");
const fetchWithPay = wrapFetchWithPayment(fetch, account);
const res = await fetchWithPay("https://cabrini.ai/v1/query", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ticker: "AAPL", date: "2024-01-15" }),
});
Operational notes for agents
| Topic | Detail |
|---|
| Rate limit | 30 requests/min per IP → 429 when exceeded |
| Health | GET /health — check before retry loops |
| No data | 404 means weekend, holiday, or ticker not yet listed — don't pay-retry |
| Idempotency | Identical request + valid payment always returns the same data |
| Timestamps | Nanoseconds since Unix epoch, UTC |
| Pricing source | GET /v1/pricing is authoritative and machine-readable, free |
A2A
The agent card at /.well-known/agent-card.json advertises capabilities (market-data, historical-prices, minute-bars) and declares x402 as the authentication scheme. A2A clients should treat Cabrini as a data-provider agent with per-request payment and no session state.