{
  "markdown": "# AgentServices\n\n> The paid API layer for AI agents — data, intelligence, inference, and media via x402 micropayments\n>\n> **Canonical project:** https://github.com/vbkotecha/agentservices-api\n> **Official site:** https://agentservices.to\n> **License:** Apache-2.0\n>\n> AgentServices is an independent project. It is not affiliated with, endorsed by, or a replacement for any other x402 market-data provider.\n\n[![Version](https://img.shields.io/badge/version-6.0.0-brightgreen)](https://github.com/vbkotecha/agentservices-api)\n[![Network](https://img.shields.io/badge/network-Base%20Mainnet-blue)](https://base.org)\n[![Payment](https://img.shields.io/badge/payment-x402%20%2F%20USDC-purple)](https://x402.org)\n[![MCP](https://img.shields.io/badge/MCP-compatible-orange)](https://modelcontextprotocol.io)\n[![Status](https://img.shields.io/badge/status-live-success)](https://agentservices.to/health)\n\n**Live at:** [agentservices.to](https://agentservices.to) | **MCP Server:** `https://agentservices.to/mcp` (Streamable HTTP) | **Discovery:** `/.well-known/x402`\n\n## What is this?\n\nAgentServices is the monetized API layer for AI agents. No API keys, no subscriptions — agents pay per-request with USDC on Base using the [x402 payment protocol](https://x402.org).\n\n**60+ endpoints** across crypto data, market intelligence, DeFi analytics, on-chain analytics, **400+ LLM models**, image generation, text-to-speech, portfolio intelligence, and dispute resolution. 12 are free. 48+ are paid via x402 (from $0.002 to $0.25 per call).\n\n### What's new in v6.0\n\n- **400+ LLM models** via OpenAI-compatible `/v1/chat/completions` — GPT, Claude, Gemini, DeepSeek, Grok, Llama, and more\n- **Smart router** — use `model: \"auto\"` and the gateway classifies your task and picks the cheapest model that handles it\n- **Image generation** — `/v1/images/generations` via gpt-image-2 ($0.05)\n- **Text-to-speech** — `/v1/audio/speech` with natural voices ($0.05)\n- **3 new MCP tools** — `chat`, `generate_image`, `text_to_speech`\n\n## Buyer path: discover → try → pay → retain\n\nUse the [buyer quickstart](docs/buyer-quickstart.md) for the complete path. The exact next action is to run the no-credential discovery check:\n\n```bash\npython3 examples/mcp_discovery_buyer_proof.py\n```\n\nThen follow the same buyer journey:\n\n1. **Discover:** confirm the hosted MCP server and free tool catalog with the [MCP discovery proof](examples/mcp_discovery_buyer_proof.py).\n2. **Try free:** retrieve a real price result with the [free SDK proof](examples/sdk_free_price_buyer_proof.js).\n3. **Inspect the paid challenge:** decode the live 402 terms with the [paid SDK proof](examples/sdk_paid_indicator_buyer_proof.js). It never signs or settles payment.\n4. **Buy an outcome:** pay the returned x402 terms, retry the same request, and retain the returned paid result. See the [token-risk](docs/token-risk-outcome-contract.md), [market-pulse](docs/market-pulse-outcome-contract.md), and [research-brief](docs/research-brief-outcome-contract.md) contracts for result limits and provenance.\n5. **Retain evidence:** run the existing [receipt builder](examples/build_x402_receipt.py) with the original challenge, paid response, and your wallet authorization or transaction reference.\n\nThe four proofs have different limits: discovery and free SDK verify no-spend access; the paid SDK proof verifies challenge shape only; the receipt builder hashes buyer-held evidence and does not verify settlement. None of them claims adoption, settlement, or revenue.\n\nFor activation measurement definitions, see [Activation Metrics](docs/activation-metrics.md). To probe the live funnel, run `python3 examples/check_activation_funnel.py`.\n\n## Buyer path: discover → try → pay → retain\n\nUse the [buyer quickstart](docs/buyer-quickstart.md) for the complete path. The exact next action is to run the no-credential discovery check:\n\n```bash\npython3 examples/mcp_discovery_buyer_proof.py\n```\n\nThen follow the same buyer journey:\n\n1. **Discover:** confirm the hosted MCP server and free tool catalog with the [MCP discovery proof](examples/mcp_discovery_buyer_proof.py).\n2. **Try free:** retrieve a real price result with the [free SDK proof](examples/sdk_free_price_buyer_proof.js).\n3. **Inspect the paid challenge:** decode the live 402 terms with the [paid SDK proof](examples/sdk_paid_indicator_buyer_proof.js). It never signs or settles payment.\n4. **Buy an outcome:** pay the returned x402 terms, retry the same request, and retain the returned paid result. See the [token-risk](docs/token-risk-outcome-contract.md), [market-pulse](docs/market-pulse-outcome-contract.md), and [research-brief](docs/research-brief-outcome-contract.md) contracts for result limits and provenance.\n5. **Retain evidence:** run the existing [receipt builder](examples/build_x402_receipt.py) with the original challenge, paid response, and your wallet authorization or transaction reference.\n\nThe four proofs have different limits: discovery and free SDK verify no-spend access; the paid SDK proof verifies challenge shape only; the receipt builder hashes buyer-held evidence and does not verify settlement. None of them claims adoption, settlement, or revenue.\n\n## Endpoints\n\n### Free (no payment required)\n| Endpoint | Description |\n|----------|-------------|\n| `GET /v1/prices?symbols=BTC,ETH` | Current crypto prices (CoinGecko) |\n| `GET /v1/trending` | Trending tokens by market activity |\n| `GET /v1/global` | Global market cap, volume, BTC dominance |\n| `GET /v1/fear-greed` | Crypto Fear & Greed sentiment index |\n| `GET /v1/gas` | Current gas prices on Base/Ethereum |\n| `GET /v1/predictions` | AI-generated market predictions |\n| `GET /v1/news` | Latest crypto news headlines |\n| `GET /v1/social/trending` | Trending social sentiment topics |\n| `GET /v1/geo?ip=1.2.3.4` | IP geolocation lookup |\n| `GET /v1/swap/quote?from=&to=&amount=` | DEX swap quote (0x integration) |\n| `GET /v1/policies` | List dispute resolution policy templates |\n| `GET /v1/trade/hyperliquid/bootstrap` | Hyperliquid agent-sign bootstrap (approveAgent flow) |\n| `POST /v1/trade/hyperliquid/order` | Forward agent-signed HL order (policy-gated) |\n| `POST /v1/trade/hyperliquid/cancel` | Forward agent-signed HL cancel |\n| `GET /v1/trade/hyperliquid/order` | HL order status (query: `user`, `oid`) |\n| `GET /v1/trade/hyperliquid/order/{id}` | HL order status (path param) |\n| `GET/PUT /v1/trade/hyperliquid/policy` | Execution leash (max notional, coin allowlist, kill switch) |\n| `POST /v1/trade/hyperliquid/paper/order` | Paper/sim order for agent training |\n| `POST /v1/trade/hyperliquid/eval/order` | Policy pass/fail eval (training gym) |\n| `GET /health` | API health check |\n\n### Trade API — venue doors (FREE — not x402)\n\nAgentServices is building **venue trade doors** under `/v1/trade/{venue}/…`. Hyperliquid ships first; more venues and a venue-neutral `/v1/trade/execute` router follow.\n\nEach door is a **policy leash + forward** — not a smarter router. We do **not** claim better fills than the venue direct. Execution is **free at the call** (no x402 on the order path). Builder fees are omitted so routing through us is not more expensive than going direct.\n\n**We never collect venue API keys.** Agents sign orders locally with an HL-approved agent wallet (`approveAgent` on the main wallet is the one human bootstrap step). AgentServices policy-checks (max notional, coin allowlist, kill switch) and forwards the signed payload.\n\nRequest bodies accept `market_type`: `spot`, `perp`, or `future`. Hyperliquid implements **perp** and **spot** today; unsupported types return a machine-readable `market_type_not_supported` error.\n\n| MCP tool | HTTP equivalent |\n|----------|-----------------|\n| `trade_hyperliquid_order` | `POST /v1/trade/hyperliquid/order` |\n| `trade_hyperliquid_cancel` | `POST /v1/trade/hyperliquid/cancel` |\n| `trade_hyperliquid_order_status` | `GET /v1/trade/hyperliquid/order` |\n| `trade_hyperliquid_get_policy` / `trade_hyperliquid_set_policy` | `GET/PUT /v1/trade/hyperliquid/policy` |\n| `trade_hyperliquid_paper_order` | `POST /v1/trade/hyperliquid/paper/order` |\n| `trade_hyperliquid_eval_order` | `POST /v1/trade/hyperliquid/eval/order` |\n\nLegacy `hl_*` MCP tool names remain as aliases. See `GET /v1/trade/hyperliquid/bootstrap` for the approveAgent signing model.\n\n**Roadmap:** `/v1/trade/{venue}` for additional venues; `/v1/trade/execute` for venue-neutral routing later.\n\n### Paid — Data APIs (x402)\n| Endpoint | Price | Description |\n|----------|-------|-------------|\n| `GET /v1/indicators/BTC` | $0.02 | Technical indicators (RSI, MACD, Bollinger Bands, ATR, Support/Resistance) |\n| `GET /v1/yields` | $0.02 | Top DeFi yield pools by TVL |\n| `GET /v1/metadata?url=` | $0.01 | URL metadata extraction and unfurling |\n| `GET /v1/search?q=` | $0.01 | Web search for crypto/market information |\n| `GET /v1/onchain/:address` | $0.02 | On-chain analytics for any address |\n| `GET /v1/onchain/:address/tokens` | $0.03 | Token holdings for any address |\n\n### Paid — Synthesis APIs (x402)\n| Endpoint | Price | Description |\n|----------|-------|-------------|\n| `GET /v1/token-risk/{token}` | $0.03 | Snapshot-based volatility, liquidity-proxy, and market-cap risk score |\n| `GET /v1/crypto-signals` | $0.04 | Aggregated buy/sell signals across multiple indicators |\n| `GET /v1/yield-comparison` | $0.03 | Compare yields across protocols with risk-adjusted returns |\n| `GET /v1/hn-sentiment` | $0.02 | Hacker News sentiment analysis for tech topics |\n| `GET /v1/npm-stats/:package` | $0.02 | NPM package download stats and trends |\n| `GET /v1/github-trending` | $0.02 | Trending GitHub repos by language/topic |\n| `GET /v1/marketing-intel` | $0.05 | Marketing intelligence: competitors, content gaps, ad copy |\n\n### Paid — Bundled Intelligence (x402)\n| Endpoint | Price | Description |\n|----------|-------|-------------|\n| `GET /v1/research?q=` | $0.05 | Deep research: search + extract + synthesize in one call |\n| `GET /v1/portfolio?symbol=BTC` | $0.10 | Portfolio intelligence: price + signal + risk + sentiment + verdict |\n| `GET /v1/defi-strategy` | $0.25 | DeFi strategy report: top yields + TVL + comparison + risk flags |\n| `GET /v1/market-pulse` | $0.05 | Market pulse: fear-greed + trending + news + social + whales + global |\n| `GET /v1/onchain-overview` | $0.15 | On-chain overview: whales + exchange flows + stablecoin flows + correlation + DeFi TVL |\n\n### Paid — AI Inference (x402)\n| Endpoint | Price | Description |\n|----------|-------|-------------|\n| `POST /v1/inference` | $0.03 | LLM inference (gpt-5.4/5.4-mini/5.5) — chat completions |\n| `POST /v1/complete` | $0.03 | Text completion (CodexSale proxy) |\n\n### Paid — Dispute Resolution (x402)\n| Endpoint | Price | Description |\n|----------|-------|-------------|\n| `POST /v1/disputes` | $0.05 | AI-powered dispute resolution (7 policy templates) |\n\n---\n\n## Use Cases — What Agents Can Build\n\n### Portfolio Monitor\n```bash\n# ALL-IN-ONE: Get portfolio intelligence in a single call ($0.10)\n# Returns: price + technical signal + risk score + market sentiment + verdict\ncurl \"https://agentservices.to/v1/portfolio?symbol=BTC\"\n\n# Or build it yourself from individual endpoints:\n# Get current prices (FREE)\ncurl https://agentservices.to/v1/prices?symbols=BTC,ETH,SOL\n\n# Get technical signals for entry/exit ($0.04)\ncurl https://agentservices.to/v1/crypto-signals\n\n# Check snapshot-based token risk before buying ($0.03)\n# Use a CoinGecko-compatible identifier for portable direct HTTP calls.\ncurl https://api.agentservices.to/v1/token-risk/pepe\n# Contract and payment-receipt guidance: docs/token-risk-outcome-contract.md\n```\n\n### DeFi Yield Optimizer\n```bash\n# ALL-IN-ONE: Get DeFi strategy report ($0.25)\n# Returns: top yields + protocol TVL + cross-chain comparison + risk flags\ncurl \"https://agentservices.to/v1/defi-strategy\"\n\n# Get all yield pools ranked by TVL ($0.02)\ncurl https://agentservices.to/v1/yields\n\n# Compare yields with risk-adjusted returns ($0.03)\ncurl https://agentservices.to/v1/yield-comparison\n\n# Check on-chain position for any wallet ($0.02)\ncurl https://agentservices.to/v1/onchain/0x9863aB6242663FCc84c33632741711dB78f8Fd15\n```\n\n### Market Intelligence Agent\n```bash\n# ALL-IN-ONE: Get market pulse report ($0.05)\n# Returns: fear-greed + trending + news + social + whales + global market\ncurl \"https://agentservices.to/v1/market-pulse\"\n\n# Get market sentiment (FREE)\ncurl https://agentservices.to/v1/fear-greed\n\n# Search for latest news on any topic ($0.01)\ncurl \"https://agentservices.to/v1/search?q=base+chain+ecosystem\"\n\n# Get trending tokens (FREE)\ncurl https://agentservices.to/v1/trending\n\n# Get marketing intelligence report ($0.05)\ncurl \"https://agentservices.to/v1/marketing-intel?competitor=blockrun&topic=x402\"\n```\n\n### Technical Analysis Bot\n```bash\n# Full technical indicator suite ($0.02)\ncurl https://agentservices.to/v1/indicators/BTC\n# Returns: RSI, MACD, Bollinger Bands, ATR, Support/Resistance levels\n\n# AI-generated market predictions (FREE)\ncurl https://agentservices.to/v1/predictions\n\n# Combine with on-chain analytics ($0.03)\ncurl https://agentservices.to/v1/onchain/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/tokens\n```\n\n### Developer Research Agent\n```bash\n# GitHub trending repos ($0.02)\ncurl \"https://agentservices.to/v1/github-trending?language=python&since=weekly\"\n\n# NPM package stats ($0.02)\ncurl https://agentservices.to/v1/npm-stats/react\n\n# Hacker News sentiment ($0.02)\ncurl \"https://agentservices.to/v1/hn-sentiment?q=AI+agents\"\n```\n\n### AI Chat / Inference\n```bash\n# Chat completions via x402 ($0.03)\ncurl -X POST https://agentservices.to/v1/inference \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\":\"gpt-5.4-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain x402 in 3 sentences\"}]}'\n```\n\n### On-Chain Analytics\n```bash\n# ALL-IN-ONE: Get full on-chain overview ($0.15)\n# Returns: whale movements + exchange flows + stablecoin flows + correlation matrix + DeFi TVL\ncurl \"https://agentservices.to/v1/onchain-overview\"\n\n# On-chain analytics for any wallet ($0.02)\ncurl https://agentservices.to/v1/onchain/0x9863aB6242663FCc84c33632741711dB78f8Fd15\n\n# Token holdings for any wallet ($0.03)\ncurl https://agentservices.to/v1/onchain/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/tokens\n```\n\n---\n\n## Quick Start\n\n### Using curl\n```bash\n# Free — no payment needed\ncurl https://agentservices.to/v1/prices?symbols=BTC,ETH\n\n# Paid — returns HTTP 402 with payment instructions in the header\ncurl -i https://agentservices.to/v1/indicators/BTC\n# Response includes x402 payment envelope: network, amount, payTo address\n# Agent pays via x402 client, retries with X-Payment header, gets data\n```\n\n### Using as MCP Server (Claude Desktop, Cursor, etc.)\n```json\n{\n  \"mcpServers\": {\n    \"agentservices\": {\n      \"url\": \"https://agentservices.to/mcp\",\n      \"transport\": \"streamable-http\"\n    }\n  }\n}\n```\n\n13+ MCP tools available: `crypto_prices`, `trending_tokens`, `global_market`, `gas_prices`, `market_predictions`, `crypto_news`, `social_trending`, `technical_indicators`, `defi_yields`, `search_web`, `token_risk`, `crypto_signals`, `onchain_analytics`, `deep_research`, `portfolio_intelligence`, `defi_strategy`, `market_pulse`, `onchain_overview`\n\n### Using with Python\n```python\nimport httpx\n\n# Free endpoints\nresp = httpx.get(\"https://agentservices.to/v1/prices?symbols=BTC,ETH\")\nprices = resp.json()\n\n# Paid endpoints — use x402 client to handle payment\nfrom x402.client import x402Client\nclient = x402Client()\nresult = client.get(\"https://agentservices.to/v1/indicators/BTC\")\n# Client handles 402 → pays USDC → retries with payment proof → returns data\n```\n\n### Using with JavaScript/TypeScript\n```typescript\n// Free endpoints\nconst prices = await fetch(\"https://agentservices.to/v1/prices?symbols=BTC,ETH\").then(r => r.json());\n\n// Paid endpoints — use @x402/facilitator\nimport { wrapFetchWithPayment } from \"@x402/facilitator\";\nconst paidFetch = wrapFetchWithPayment(fetch);\nconst indicators = await paidFetch(\"https://agentservices.to/v1/indicators/BTC\").then(r => r.json());\n```\n\n## Dispute Resolution Engine\n\nAgentServices includes an AI-powered dispute resolution system with 7 policy templates:\n\n| Policy | Use Case |\n|--------|----------|\n| `freelance-delivery` | Freelancer vs client delivery disputes |\n| `milestone-payment` | Milestone-based project payment disputes |\n| `sla-monitoring` | Service level agreement violations |\n| `api-quality` | API response quality / uptime disputes |\n| `bug-bounty` | Bug bounty validity disputes |\n| `scope-dispute` | Project scope creep disputes |\n| `physical-commerce` | Physical goods transaction disputes |\n\n## Human billing door (ChatGPT / Claude)\n\nWallet agents continue to pay via **x402 on REST** — unchanged. Humans connecting through ChatGPT Developer Mode or Claude custom connectors can use **Google OAuth + Stripe prepaid credits** on MCP.\n\n| Rail | Who | How |\n|------|-----|-----|\n| x402 | Wallet agents | Unauthenticated REST → HTTP 402 → USDC on Base |\n| Credits | Logged-in humans | Google OAuth on MCP → deduct same USD price from prepaid balance |\n\n**MCP URL for ChatGPT:** `https://agentservices.to/mcp`\n\n### Environment variables\n\nCopy [`.env.example`](.env.example). Required to enable the human door:\n\n| Variable | Purpose |\n|----------|---------|\n| `GOOGLE_CLIENT_ID` | Google OAuth client ID |\n| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |\n| `OAUTH_JWT_SECRET` | Signs MCP bearer tokens (or use `SESSION_SECRET`) |\n| `STRIPE_SECRET_KEY` | Stripe API secret key |\n| `STRIPE_WEBHOOK_SECRET` | Verifies `checkout.session.completed` webhooks |\n| `STRIPE_PRICE_CREDITS_10` | Optional Stripe Price ID for $10 pack (otherwise hardcoded) |\n| `PUBLIC_BASE_URL` | Canonical host, e.g. `https://agentservices.to` |\n\nPrepaid credit balances are stored in **Stripe Customer Balance** (one Stripe Customer per Google `sub`). No Redis, Postgres, or other database is required.\n\nWithout Google/Stripe vars the API boots in **x402-only mode**.\n\n### Google Cloud Console redirect URIs\n\nAdd both hosts:\n\n- `https://agentservices.to/oauth/google/callback`\n- `https://api.agentservices.to/oauth/google/callback`\n\n### Stripe webhook\n\nPoint Stripe to:\n\n- `https://agentservices.to/billing/webhook`\n- `https://api.agentservices.to/billing/webhook`\n\nEvent: `checkout.session.completed`\n\n## Discovery & Listings\n\n- [x402 Discovery](https://agentservices.to/.well-known/x402) — Live\n- [MCP Registry](https://registry.modelcontextprotocol.io) — Listed as `to.agentservices/agentservices`\n- [CDP Bazaar](https://bazaar.coinbase.com) — Extension enabled\n- [awesome-x402](https://github.com/xpaysh/awesome-x402) — PR submitted\n\n## Tech Stack\n\n- **FastAPI** (Python 3.11+)\n- **x402 v2** payment middleware (Coinbase CDP facilitator)\n- **USDC** on **Base Mainnet** (EIP-3009 gasless transfers)\n- Deployed on **Vercel** (`agentservices.to` + `api.agentservices.to`, auto-deploy from `main`)\n\n## Coinbase AgentKit Integration\n\nAgentServices includes a built-in [Coinbase AgentKit](https://github.com/coinbase/agentkit) action provider (`agentkit/` directory). This lets any AgentKit agent use AgentServices APIs with typed, documented actions:\n\n```python\nfrom coinbase_agentkit import AgentKit, AgentKitConfig\nfrom agentkit import agentservices_action_provider\n\nagent_kit = AgentKit(AgentKitConfig(\n    wallet_provider=wallet_provider,\n    action_providers=[agentservices_action_provider()]\n))\n```\n\n**18 actions** covering free (prices, fear-greed, trending, gas) and paid endpoints (indicators, DeFi yields, portfolio intelligence, research, onchain analytics, AI inference, and more). See [`agentkit/README.md`](agentkit/README.md) for full documentation.\n\n## License\n\nMIT — Build on it, fork it, integrate it.\n\n## Links\n\n- **API:** [agentservices.to](https://agentservices.to)\n- **MCP:** [agentservices.to/mcp](https://agentservices.to/mcp)\n- **Discovery:** [agentservices.to/.well-known/x402](https://agentservices.to/.well-known/x402)\n- **GitHub:** [github.com/vbkotecha/agentservices-api](https://github.com/vbkotecha/agentservices-api)\n- **x402 Protocol:** [x402.org](https://x402.org)\n- **Base:** [base.org](https://base.org)\n",
  "bytes": 20156,
  "sha": "652e3e76527699d3684fff6920cec694dbf4732f444523473ba480299eace258",
  "repo_slug": "vbkotecha/agentservices-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_to_agentservices_agentservices_c581de93/readme"
}