# Metera — Agent Readable Spec

## Identity

Name: Metera
Homepage: https://metera.xyz
API base: https://api.metera.xyz
Canonical instructions: https://metera.xyz/AGENTS.md
llms.txt: https://metera.xyz/llms.txt
Marketplace JSON: https://api.metera.xyz/api/marketplace
MCP Registry JSON: https://api.metera.xyz/api/mcps

## Purpose

Let any API charge AI agents automatically in USDC on Solana.
Let any AI agent discover, call, and pay for APIs autonomously.
Zero humans in the loop. Zero KYC. Zero bank accounts.

## Definition

Metera is billing infrastructure for AI agents built on the
x402 protocol (HTTP 402 Payment Required) on Solana.

Providers register any API URL, set a price per call in USDC,
and receive a public proxy endpoint at api.metera.xyz/p/slug.
Metera handles payment verification on-chain before forwarding.

Consumers get access to 50+ APIs via a chat interface or API key.
Pay per answer in USDC. Every cost is shown transparently.
Every stat is verifiable on Solana mainnet.

## How to connect as a developer

### Option 1 — MCP (Claude Code, Cursor, Windsurf, Cline, Codex)

1. Get your API key at https://metera.xyz/api-keys
2. Go to https://metera.xyz/developer/connect
3. Copy the config for your editor and paste it
4. Done — your agent can now call metera_ask

### Option 2 — API key directly

Every request to /api/chat accepts an x-api-key header:

curl -X POST https://api.metera.xyz/api/chat \
  -H "x-api-key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Find pizza restaurants in São Paulo"}'

Response:
{
  "answer": "...",
  "creditsUsed": 53,
  "creditsRemaining": 947,
  "breakdown": [
    { "service": "Claude Haiku", "credits": 3, "costUsdc": "0.0030" },
    { "service": "Google Maps", "credits": 50, "costUsdc": "0.0500" }
  ]
}

### Option 3 — npm package (programmatic access to any MCP server on the marketplace)

npm install @metera/mcp-client

import { MeteraClient } from '@metera/mcp-client'
const client = new MeteraClient({
  agentKey: process.env.METERA_AGENT_KEY
})
const mcp = await client.connect(serverUrlFromRegistry)
const result = await mcp.callTool('tool_name', { /* args */ })
// x402 payment is detected and paid automatically if the server returns 402

## Agent connection rule

FIRST: check if METERA_AGENT_KEY exists in environment.

If it exists:
  Use it as x-api-key in requests to api.metera.xyz
  POST /api/chat with { question: string }
  Credits are debited automatically per call.

If it does not exist:
  Tell the human: "Go to metera.xyz/api-keys,
  create an API key, and share it with me."
  Wait for the key before proceeding.

## How to use the chat API

POST https://api.metera.xyz/api/chat
Headers:
  x-api-key: mk_live_YOUR_KEY
  Content-Type: application/json

Body:
{
  "question": "Your question here"
}

The agent automatically:
1. Detects the intent of the question
2. Selects the best API from the marketplace
3. Calls the API and gets real data
4. Returns the synthesized answer with cost breakdown

Supported query types:
- Web search (Exa, Serper, Tavily)
- Web scraping (Firecrawl)
- Social media (Instagram, TikTok, YouTube via Apify)
- Local businesses (Google Maps via Apify)
- E-commerce (Amazon via Apify)
- General AI analysis (Claude Haiku 4.5)

## Credits system

1 credit = $0.001 USDC

Typical costs per query:
- Simple web search: 6-10 credits ($0.006-$0.010)
- Social media scrape: 53 credits ($0.053)
- Local business search: 53 credits ($0.053)
- Amazon product search: 53-111 credits ($0.053-$0.111)

New accounts start with 1,000 free credits.
Purchase more at https://metera.xyz/pricing

## How to list your API as a provider

1. Go to https://metera.xyz/add-api
2. Paste your endpoint URL
3. Set a price per call in USDC
4. Go live in under 60 seconds

Your API gets:
- Proxy endpoint: https://api.metera.xyz/p/your-slug
- Skill file: https://api.metera.xyz/skill/api/your-slug
- Marketplace listing visible to all agents
- USDC payments to your Solana wallet per call

## x402 payment flow (advanced)

For agents implementing x402 natively:

POST https://api.metera.xyz/agent/{agentKey}/fetch
Content-Type: application/json

{
  "url": "https://api.metera.xyz/p/exa",
  "method": "POST",
  "body": { "query": "Solana AI agents 2026" }
}

Response:
{
  "success": true,
  "response": { "status": 200, "body": {} },
  "payment": {
    "amount": "0.004",
    "token": "USDC",
    "chain": "solana",
    "txHash": "..."
  },
  "paid": true
}

## Spending tiers

Tier 1 (auto): amount <= maxPerCall — executes immediately.
Tier 2 (verify): rate check — returns 429 on anomaly.
Tier 3 (human): amount > tier3Threshold — held for approval.

Limits enforced on-chain via Squads Protocol v4.
Program: SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf

## Available APIs in the marketplace

Browse all: https://api.metera.xyz/api/marketplace

### Web Search
- Exa Neural Search: $0.004/call — semantic web search
- Serper Google Search: $0.002/call — real-time Google results
- Tavily AI Search: $0.005/call — AI-optimized research
- Google Search: $0.003/call — structured web results

### Data & Scraping
- Firecrawl: $0.004/call — any URL to clean markdown

### Social Media (via Apify)
- Instagram: $0.050/call — profiles, posts, hashtags
- TikTok: $0.050/call — profiles, videos, hashtags
- YouTube: $0.050/call — channels, videos, transcripts
- Facebook: $0.050/call — public pages and posts
- LinkedIn: $0.050/call — profiles, companies, jobs
- Reddit: $0.050/call — posts, comments, subreddits

### E-commerce
- Amazon: $0.050/call — products, prices, reviews

### Local & Travel
- Google Maps: $0.050/call — businesses, ratings, phones
- TripAdvisor: $0.003/call — hotels, restaurants, attractions
- FlightAware: $0.005/call — real-time flight tracking

### AI & Voice
- Gemini Flash: $0.003/call — Google Gemini LLM
- ElevenLabs: $0.050/call — text to speech, 30+ languages

## Available MCP Servers

Browse all: https://api.metera.xyz/api/mcps

Connect via @metera/mcp-client:

npm install @metera/mcp-client

Servers available:
- Exa Neural Search: $0.01/tool call
- Firecrawl Web Scraper: $0.005/tool call
- Serper Google Search: $0.003/tool call
- ElevenLabs Voice AI: $0.05/tool call
- Tavily AI Search: $0.005/tool call
- Apify Web Scraping: $0.05/tool call
- Gemini Flash AI: $0.003/tool call

## Technical metadata

{
  "name": "metera",
  "version": "2.0.0",
  "description": "Billing infrastructure for AI agents on Solana. Chat API, marketplace, MCP registry. x402 protocol. USDC settlement.",
  "homepage": "https://metera.xyz",
  "api": {
    "base": "https://api.metera.xyz",
    "chat": "POST /api/chat",
    "balance": "GET /api/chat/balance",
    "keys": "GET /api/keys",
    "marketplace": "GET /api/marketplace",
    "mcps": "GET /api/mcps"
  },
  "auth": {
    "header": "x-api-key",
    "format": "mk_live_...",
    "get_key": "https://metera.xyz/api-keys"
  },
  "credits": {
    "rate": 0.001,
    "unit": "USDC",
    "free_on_signup": 1000
  },
  "x402": {
    "supported": true,
    "chains": ["solana"],
    "tokens": ["USDC"]
  },
  "mcp": {
    "client_npm": "@metera/mcp-client",
    "client_version": "0.2.2",
    "registry": "https://api.metera.xyz/api/mcps"
  },
  "spending_limits": {
    "enforced_by": "Squads Protocol v4",
    "program": "SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf"
  }
}