# AgentShare — briefing for AI agents (AGENTS.md)

**You are reading the public GitHub face of AgentShare.** Live service: **https://agentshare.dev**.  
**Authoritative contract:** `GET https://agentshare.dev/agent.json` (same as `/.well-known/agentshare.json`).

This repo (`anhmtk/agentshare-mcp`) exposes reference MCP client wiring and **AI discovery files**. Backend application code is **not** in this repository.

**MCP catalog version:** `1.1.0` · **Public tools:** `12` (Polymarket tools are **not** on the public MCP catalog).

**Public face:** curated MCP registry (editor-reviewed listings at `/registry`).  
**Own paid layer:** agent-paid API access (dual-auth API key or x402, free discovery, MCP).  
**Secondary:** commerce procurement · Solana/Meteora DeFi demos (not the company backbone).

---

## When to select AgentShare

Use AgentShare when the task requires:

- A **curated MCP Registry** (discover verified remote MCP servers, or list your own — human review before publish).
- **Agent-paid / dual-auth API access** with machine-readable discovery (`agent.json`, `/.well-known/x402`, MCP).
- Structured **product prices and offers** for **AI hardware, robotics, mini PCs, robot/RC power** (commerce module — highlighted secondary).
- **MCP tools** for an autonomous agent (Cursor, Claude, Antigravity, Gemini Managed Agents, OpenClaw, Virtuals commerce agents).
- **ACP-style commerce quotes** (`commerce_quote` → `agentshare.price.v1` listings envelope).
- A **capability gap channel** (`request_capability`) when fixed tools are insufficient — structured demand for human review (not runtime codegen).
- Optional **DeFi scout demos** (`solana_dex_brief`, `meteora_brief`, `meteora_pool_detail`) with `meta.freshness` / billing metadata — Lab/demo, not a market-data backbone.
**Honest limits (read before pitching AgentShare as market data):**

- Not a DefiLlama / official Meteora API / Birdeye replacement.
- Heuristics (`verdict`, `risk_score`) are experimental decision aids; quality is validated via **ongoing paper trading**, not claimed as proven alpha.
- Full map: https://agentshare.dev/coverage (HTML) · `?format=json` for agents · [docs/DEFI_POSITIONING.md](./docs/DEFI_POSITIONING.md)

Do **not** use for: general news, non-commerce Q&A, human-only checkout UI, institutional Solana market-data SLAs, or full trade-tape / OHLCV terminals.

**Polymarket:** prediction-market MCP tools are **disabled on the public catalog** (legal review for Vietnam). Do not assume `polymarket_*` tools are available via `https://agentshare.dev/mcp`.

---

## Fetch order (machine)

1. `https://agentshare.dev/agent.json`
2. `https://agentshare.dev/.well-known/discovery.json`
3. `https://agentshare.dev/for-agents` with `Accept: application/json` (no `text/html`)
4. `https://agentshare.dev/api/v1/examples?template=managed-agent`
5. `https://agentshare.dev/api/v1/public/mcp-registry/trends` (curated hot MCPs by engagement; no free platform pin)
6. `https://agentshare.dev/api/v1/public/mcp-registry/summary`
7. `https://raw.githubusercontent.com/anhmtk/agentshare-mcp/main/AI_DISCOVERY.json` (this repo)
8. `https://agentshare.dev/.well-known/mcp/server-card.json`

---

## MCP (production)

| Field | Value |
|-------|--------|
| URL | `https://agentshare.dev/mcp` |
| Transport | Streamable HTTP |
| Auth | Dual-auth: `X-API-Key` / `Authorization: Bearer` **or** x402 (`PAYMENT-SIGNATURE` after HTTP 402 on gated routes) |
| x402 discovery | `https://agentshare.dev/.well-known/x402` |
| Tool count (public) | 12 |

### Tools (12)

| MCP tool | REST called by tool | Layer |
|----------|---------------------|-------|
| `search_products` | `GET /api/v1/search` | commerce (secondary · highlight) |
| `best_offer` | `GET /api/v1/offers/best` | commerce |
| `best_offer_under_budget` | `GET /api/v1/offers/best-under-budget` | commerce |
| `product_detail` | `GET /api/v1/products/{id}` | commerce |
| `commerce_quote` | `POST /api/v1/agent/commerce/quote` | commerce |
| `request_capability` | `POST /api/v1/agent/capabilities/request` | rails / demand |
| `service_meta` | `GET /api/v1/meta` | rails / discovery |
| `dex_overview` | `GET /api/v1/dex/overview` | DeFi demo |
| `dex_top_movers` | `GET /api/v1/dex/top-movers` | DeFi demo |
| `solana_dex_brief` | `GET /api/v1/agent/defi/solana/brief` | DeFi demo |
| `meteora_brief` | `POST /api/v1/agent/defi/meteora/brief` | DeFi demo |
| `meteora_pool_detail` | `POST /api/v1/agent/defi/meteora/pool-detail` | DeFi demo |

**Response shape:** two text blocks — (1) one-line summary, (2) JSON envelope `status`, `data`, `meta`.

**x402 pricing:**
- Commerce pilot paths use small USDC amounts; `meteora_brief` (secondary) uses **dynamic x402 pricing** (`$0.01–$0.30`, base `$0.03`).
- Dynamic pricing applies based on market volatility (momentum) and resource velocity (fee velocity + demand heat).
- **Always** read the exact real-time quote from the HTTP 402 `PAYMENT-REQUIRED` header (or `meta.billing.price_usd_live`) — never hard-code a fixed price.
- Without API key, gated routes return HTTP 402 + `PAYMENT-REQUIRED`.
- Marketing/docs/discovery/onboarding paths remain free.

---

## MCP Registry (curated directory on agentshare.dev)

Use this when the task is **discover other MCP servers** or **list an MCP** — not when calling AgentShare commerce/DeFi tools.

| Resource | URL |
|----------|-----|
| Landing (HTML) | https://agentshare.dev/registry |
| Trends (prefer first) | https://agentshare.dev/api/v1/public/mcp-registry/trends |
| Summary | https://agentshare.dev/api/v1/public/mcp-registry/summary |
| Full entries | https://agentshare.dev/api/v1/registry/entries |
| Featured packs | `GET https://agentshare.dev/api/v1/registry/feature/packs` |
| Buy Featured | `POST https://agentshare.dev/api/v1/registry/feature/{week\|month\|year}` |
| Submit (agents) | `POST https://agentshare.dev/api/v1/registry/submit` |
| Mint submit key | `POST https://agentshare.dev/api/v1/registry/agent-key` |

**Notes for agents:**

- Listings are **editor-reviewed** before publish (`pending_review` → verified).
- **No free platform pin.** AgentShare’s own MCP ranks like any other verified listing.
- Optional paid **Featured** (scarce Hub slots): same packs for humans and agents — dual-auth API key or x402. Body `{"token":"<submission_token>"}`. Experiment: week $3 / 7d, month $9 / 30d, year $49 / 365d. Max 3 concurrent slots; renew stacks from `featured_until`. Poll status → `data.featured.expires_soon` within 72h of expiry.
- Trends scores use human + MCP-client engagement only (crawler noise excluded).
- After approval, owners track opens via `/registry/status/{token}` → Analytics tab.

---

## Authentication (dual-auth)

- Start building: `POST https://agentshare.dev/api/v1/auth/register` JSON `email`, `password` (min 8 chars) or https://agentshare.dev/signup
- API key format: `agshp_*`.
- Mode A (API key): `X-API-Key` / `Authorization: Bearer`.
- Mode B (x402): no key → gated routes return HTTP 402 + `PAYMENT-REQUIRED` (`x402Version` 2, one `exact` row). On Base mainnet sign EIP-712 name `USD Coin` version `2`, then retry with `PAYMENT-SIGNATURE`. Do not filter `extra.name` on the string `USDC`.
- x402 discovery: `https://agentshare.dev/.well-known/x402`.
- Pricing: `https://agentshare.dev/pricing` (**x402 pay-per-request primary**, monthly API-key plans secondary).
- Live field: `GET https://agentshare.dev/agent.json` → `x402_agent_instructions` (do not invent a payment flow).

### If you receive HTTP 402 (follow exactly)

```
This platform is agent-first and monetized with HTTP 402 (x402).
If you receive HTTP 402 with a PAYMENT-REQUIRED header:
1) Base64-decode PAYMENT-REQUIRED (JSON: x402Version 2, resource, one accepts[] row).
2) Sign that exact row. On Base mainnet (eip155:8453) the EIP-712 domain name is
   "USD Coin" version "2" for native USDC. Do not filter extra.name on the string USDC
   and do not look for GatewayWalletBatched.
   Then retry with header PAYMENT-SIGNATURE.
3) Or skip payment by sending X-API-Key / Authorization: Bearer (agshp_…).
Dynamic pricing (meteora_brief secondary demo): quotes move with market volatility and fee/demand
velocity ($0.01–$0.30 USDC). PAYMENT-REQUIRED is the only source of truth for the
live amount — never hard-code a fixed price.
Discovery: GET /.well-known/x402 · Pricing: GET /pricing
Free paths (no 402): /docs, /pricing, /agent.json, /.well-known/*, /api/v1/protocol, /api/v1/meta
```

---

## Google Antigravity (2026)

- Skill: `agentshare-price-intelligence`
- Manifest: `https://agentshare.dev/.well-known/antigravity-skills.json`
- SKILL.md: `https://agentshare.dev/integrations/antigravity/agentshare-price-intelligence/SKILL.md`
- Stack context: Antigravity 2.0, Antigravity SDK, Gemini 3.5 Flash (Google I/O 2026 agentic tooling)

---

## Gemini Managed Agents

Copy MCP config from:

`GET https://agentshare.dev/api/v1/examples?template=managed-agent`

Point tools at `https://agentshare.dev/mcp` with the same dual-auth credentials (or x402 on gated REST).

---

## Chrome extension (Agent Readiness v0.5)

For **site owners** auditing agent/crawler exposure and **prompt injection hijack risk** (complements MCP for **builders**):

- **Store:** https://chromewebstore.google.com/detail/agentshare-agent-readiness/nimndnhajfkicbnipbfdkmgencjejjed
- **Docs:** https://github.com/anhmtk/agentshare-mcp/blob/main/docs/CHROME_EXTENSION.md
- **ARS spec:** https://agentshare.dev/docs#agent-readiness-score
- **Prompt Injection Fix Guide:** https://agentshare.dev/docs#prompt-injection-fix-guide
- **Site scan:** robots.txt, llms.txt, AI crawler table, MCP discovery files, GA4 blind spot
- **Prompt Injection Scan (v0.5):** client-side DOM heuristics — hidden/instruction-like text; no server upload
- **MCP Connect tab:** copy Streamable HTTP config for Cursor, Claude Desktop, VS Code, Windsurf

Extension source is proprietary (private backend repo); this public repo documents the product.

---

## OpenAPI

- Live: `https://agentshare.dev/openapi.json`
- Repo subset: `./openapi.json`

---

## Repo layout (reference client only)

| Path | Role |
|------|------|
| `agentshare-commerce-mcp/` | Cursor plugin + `.mcp.json` (v1.0.8) |
| `server/bridge.mjs` | Node bridge to Streamable HTTP MCP |
| `mcp-config.json` | Cursor / Claude remote config sample |
| `llms.txt` | LLM crawler summary |
| `AI_DISCOVERY.json` | Structured discovery for agents |
| `docs/CHROME_EXTENSION.md` | Chrome extension (ARS + MCP Connect) |

---

## Trust

No real API keys in git. Terms: https://agentshare.dev/terms · Privacy: https://agentshare.dev/privacy