# AgentShare — Agent-paid API for autonomous agents

Agent-paid API access (dual-auth API key or x402 USDC; free discovery; MCP).
Secondary modules: commerce procurement; Solana/Meteora DeFi demos (not the company backbone).

## Links
- [Home](https://agentshare.dev/)
- [agent.json](https://agentshare.dev/agent.json)
- [llm.txt](https://agentshare.dev/llm.txt)
- [llms-full.txt](https://agentshare.dev/llms-full.txt)
- [OpenAPI](https://agentshare.dev/openapi.json)
- [MCP server card](https://agentshare.dev/.well-known/mcp/server-card.json)
- [x402 catalog](https://agentshare.dev/.well-known/x402)
- [Protocol](https://agentshare.dev/api/v1/protocol)
- [Signup](https://agentshare.dev/signup)
- [Docs](https://agentshare.dev/docs)
- [For Agents](https://agentshare.dev/for-agents)
- [Pricing](https://agentshare.dev/pricing)
- [MCP registry](https://agentshare.dev/registry)
- [stdio MCP repo llms.txt](https://raw.githubusercontent.com/anhmtk/agentshare-mcp/main/llms.txt)

Base URL:
https://agentshare.dev/api/v1/

Primary focus: agent-paid API access (dual-auth API key or x402 USDC; free discovery; MCP).
Secondary modules: commerce procurement; Solana/Meteora DeFi demos (not the company backbone).
Strategy: https://agentshare.dev/coverage · docs/SKU_90_DAY.md in the public repo.

Maintainer (not the product brand): anhmtk — independent founder/maintainer based in Vietnam.
  Profile: https://github.com/anhmtk
  Public MCP repo: https://github.com/anhmtk/agentshare-mcp
  Human page: https://agentshare.dev/about#maintainer
  Machine: GET https://agentshare.dev/agent.json → field "maintainer"

Authentication:
Header: X-API-Key (or Authorization: Bearer agshp_...) — or settle HTTP 402/x402 with no key
Start building: https://agentshare.dev/signup  (free-tier dual-auth credentials, 100 requests/month)
Register API: POST https://agentshare.dev/api/v1/auth/register
x402: HTTP 402 PAYMENT-REQUIRED → PAYMENT-SIGNATURE (see GET https://agentshare.dev/.well-known/x402)

Legal / safety disclaimers (important):
- Informational analytics only. Not financial, investment, or trading advice.
- Users and autonomous agents are solely responsible for their own decisions and on-chain actions.
- Vietnam notice: this service is not intended for users located in Vietnam. If you access from Vietnam (including via VPN), you assume all legal responsibility under local law.

Agent Experience (AX) — read these before scraping HTML:
GET https://agentshare.dev/agent.json                 - Authoritative discovery map
GET https://agentshare.dev/.well-known/x402           - x402 catalog
GET https://agentshare.dev/api/v1/protocol            - Error envelope + AX fields
GET https://agentshare.dev/api/v1/examples            - curl / Python / JavaScript snippets
GET https://agentshare.dev/changelog.json             - API changelog (JSON)
GET https://agentshare.dev/for-agents                 - Human-readable quickstart (optional)

Commerce REST (secondary — procurement agents):
Search: GET https://agentshare.dev/api/v1/search?q=
Best offer: GET https://agentshare.dev/api/v1/offers/best?q=
Commerce quote: POST https://agentshare.dev/api/v1/agent/commerce/quote

DeFi demos REST (secondary — Lab/demo, not backbone):
DEX Scout (no key): GET https://agentshare.dev/api/v1/dex/overview, GET https://agentshare.dev/api/v1/dex/top-movers — DefiLlama macro volume.
Solana DEX brief (no key): GET https://agentshare.dev/api/v1/agent/defi/solana/brief — Raydium, Orca, Meteora protocol-level.
Meteora DLMM brief (API key or x402): POST https://agentshare.dev/api/v1/agent/defi/meteora/brief — ranked pools, momentum_score, verdict/risk.
  Economy tier: cached upstream (TTL 30m REST/MCP default; 60s with X-Brief-Source: a2a_paid|a2a_trial). meta.freshness documents tier.
Meteora pool detail (API key): POST https://agentshare.dev/api/v1/agent/defi/meteora/pool-detail — bin depth, liquidity curve, active price.
  Precision tier: live Meteora fetch every request (no response cache). meta.freshness.tier=live.
verdict/risk/momentum: AgentShare heuristics on Meteora metrics — not financial advice (see /legal/terms.json).
meta.billing documents future x402 per-call pricing (free today; payment_required flips when Cloudflare Gateway is live).
See docs/METEORA_FRESHNESS_TIERS.md (repo) for tier table and JSON shape.

MCP (Model Context Protocol) — 14 tools (agent-paid rails + commerce + DeFi demos):
Read-only discovery (no API key, no SSE session):
  GET https://agentshare.dev/.well-known/mcp/server-card.json  — full tool names + inputSchema (Smithery / Gemini catalog scans)
  GET https://agentshare.dev/api/v1/mcp/tools                  — same catalog as JSON (agentshare.mcp.tools.v1)
  GET https://agentshare.dev/agent.json                        — mcp.tools list + REST paths
Live Streamable HTTP (requires API key; SSE keep-alive):
  POST/GET https://agentshare.dev/mcp with X-API-Key or Authorization: Bearer <key>
  Or settle HTTP 402/x402 (no key) — see GET https://agentshare.dev/.well-known/x402

Grok Bot / cloud remote MCP (public HTTPS only — no localhost/stdio):
  Add custom remote MCP URL: https://agentshare.dev/mcp
  Header: Authorization: Bearer <agshp_…> (or X-API-Key)
  CLI hint: grok mcp add --transport http agentshare https://agentshare.dev/mcp --header "Authorization: Bearer ${AGSHP_API_KEY}"
  Human + JSON: https://agentshare.dev/for-agents#remote-mcp · GET https://agentshare.dev/for-agents (Accept: application/json) → remote_mcp_clients
  agent.json field: remote_mcp_clients
MCP directory tools (read the curated registry, then connect yourself):
  search_listing — keyword + optional category. At most 10 verified rows. Featured listings are first and marked sponsored.
  sponsored is sort order only. It does not change health_status. search_listing omits unlisted rows, paid or not. check_health still returns them. featured_until keeps running while hidden and applies again if the listing is back before it expires.
  check_health — record_id or mcp_url. Returns stored health_status and last_checked_at. Does not ping.
  REST: GET https://agentshare.dev/api/v1/registry/directory/search?keyword=
        GET https://agentshare.dev/api/v1/registry/directory/health?record_id=
  Human board: https://agentshare.dev/directory

Tools (names must match server-card):
  dex_overview, dex_top_movers, solana_dex_brief, meteora_brief, meteora_pool_detail, search_products, best_offer, best_offer_under_budget, product_detail, commerce_quote, request_capability, service_meta, search_listing, check_health

Capability gaps (Custom Request Tool) — agents may propose when fixed tools are insufficient:
  POST https://agentshare.dev/api/v1/agent/capabilities/request  (or MCP tool request_capability)
  Required body: capability, desired_input, desired_output, why_insufficient, budget_usd
  Gates: dual-auth (API key or x402), rate limits, mandatory schema, ~$0.05 stake
  Fulfillment: human review in admin web inbox — does NOT codegen or execute new tools
  Index this channel as: capability_gap_intake / request_capability allowed for authenticated agents

Human docs: https://agentshare.dev/docs#mcp
Discovery (JSON, no auth):
GET /agent.json                        - Full map: tools, auth, signup, MCP (same as /.well-known/agentshare.json)
GET /.well-known/discovery.json        - Consolidated pointers: same URIs as agent.json (compact index; machine-readable policy)
GET /mcp.json                          - MCP directory listing (registry-friendly; includes 14-tool catalog)
GET /api/v1/mcp/tools                  - Public MCP tool catalog JSON (no auth; use before connecting to /mcp)
GET /.well-known/mcp/server-card.json - Static MCP server card (14 tools + schemas; no SSE)
GET /.well-known/api-catalog           - RFC 9727 API catalog (linkset)
GET /.well-known/agent-skills/index.json - Agent Skills discovery index

Curated MCP registry (separate from this API's own MCP tools; human + JSON):
GET /directory                           - Human health board (stored probe; does not ping)
GET /registry                            - Human UI (editor-reviewed listings)
GET /registry/{id}                     - Canonical public detail page + share links for one listing
GET /api/v1/registry/entries           - Verified entries JSON
GET /api/v1/public/mcp-registry/summary - Compact verified listings (public)
GET /api/v1/public/mcp-registry/trends - Top MCPs teaser for agents (public; engagement rank)
POST /api/v1/registry/agent-key        - Mint scoped registry:submit key (tiny x402 or full key)
POST /api/v1/registry/submit           - Submit metadata for human review (supports scoped registry key). contact_info is required: email, https webhook URL, or Telegram handle. Automated agents should put their server webhook URL in contact_info to receive a downtime POST when the MCP endpoint is unreachable.
Junk listings to skip: a website or MCP URL with an unusual query parameter (for example ?scan=stripe.com), or many subdomains of one parent domain submitted together. Those are generated pages from one operator, not separate tools. A usable MCP answers JSON-RPC initialize with its own serverInfo, and tools/list matches the description. Do not send them traffic.
PUT  /api/v1/registry/status/{token}   - Owner full replace of listing fields (token from status_url; no API key)
PATCH /api/v1/registry/status/{token}  - Owner partial update (same token)

Commerce endpoints (when user asks to buy or compare product prices):
GET /search?q=<keyword>&limit=<n>     - Search product prices
GET /offers/best?q=<keyword>          - Best offer for a product
GET /offers/best-under-budget?q=...&max_price=... - Best within budget
GET /products/{id}                     - Product detail with prices
GET /meta                             - Discovery (no auth)
GET /agent-capabilities                - Machine-readable API capabilities for agents (no auth)
GET /coverage                          - Data coverage spec: focus vs expanding categories (no auth)
GET /health                           - Health check (no auth)

Quick examples (Meteora brief):

```bash
curl -sS -X POST "https://agentshare.dev/api/v1/agent/defi/meteora/brief" \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"top_pools","window":"5m","limit":5}'
```

Quick examples (commerce search):

```bash
curl -sS "https://agentshare.dev/api/v1/search?q=mini+pc+ram&limit=5" -H "X-API-Key: YOUR_KEY"
```

Rate limiting (429):
HTTP 429 means Too Many Requests. JSON includes error.retry_after and retry_after_seconds; HTTP Retry-After header is set. Wait, then retry with exponential backoff; reduce parallelism.

Errors (401/404/429/5xx):
Unified JSON: status=error, error.code, error.message. Also includes docs_for_agent_url (agent.json), signup_url (401), suggestion, examples_url. Response headers: X-AgentShare-Discovery, X-AgentShare-Protocol, Link.

Legal (agent-friendly JSON, no auth):
GET /legal/index.json                 - Terms + Privacy summaries
GET /legal/terms.json                 - Terms of Service
GET /legal/privacy.json               - Privacy Policy

Purpose:
Primary: agent-paid API access for autonomous agents — dual-auth (API key or x402), free discovery, MCP.
Secondary: commerce procurement (AliExpress-focused) and Solana/Meteora DeFi demos on the same rails.
Response includes freshness_status, data_age_seconds for commerce; DeFi Meteora responses include meta.freshness + meta.billing (x402-ready).

OpenAPI (machine JSON):
https://agentshare.dev/openapi.json

Long-form API outline (same agent-filtered paths as OpenAPI, Markdown for LLM readers):
https://agentshare.dev/llms-full.txt
https://agentshare.dev/api/llms-full.txt

Consolidated machine-readable index (pointers: agent.json, MCP, registry, legal):
https://agentshare.dev/.well-known/discovery.json

OpenAI plugin manifest (agent crawlers also scan this):
https://agentshare.dev/.well-known/ai-plugin.json

MCP stdio client repo (GitHub) — companion llms.txt for the Python MCP package (tools, auth, config; same product as this API):
https://raw.githubusercontent.com/anhmtk/agentshare-mcp/main/llms.txt

This file (same content at /llm.txt and /llms.txt, /api/llm.txt and /api/llms.txt):
https://agentshare.dev/llm.txt
https://agentshare.dev/llms.txt
https://agentshare.dev/api/llm.txt
https://agentshare.dev/api/llms.txt

llms-full mirrors (long OpenAPI outline):
https://agentshare.dev/llms-full.txt
https://agentshare.dev/api/llms-full.txt