@dexterai/mcp 0.1.3 → 0.1.4

package/README.md

@@ -1,20 +1,31 @@
 # @dexterai/mcp
 
-x402 gateway for AI agents. Search, pay, and call any x402 API through Dexter.
+x402 gateway for AI agents. Search, pay, and call any x402-protected API through Dexter — the world's most-used x402 facilitator.
 
-## Install
+Your agent gets four tools: discover paid APIs, check pricing, pay automatically, and manage its wallet. One package, every chain.
 
-### Guided Install (recommended)
+## Quick Start
 
 ```bash
 npx @dexterai/mcp install
 ```
 
-Supports: **Cursor**, **Claude Code**, **Codex**, **VS Code**, **Windsurf**, **Gemini CLI**
+That's it. Pick your client, the installer writes the config. On first run a Solana wallet is created at `~/.dexterai-mcp/wallet.json`. Fund it with USDC and your agent can start paying for APIs.
 
-### Manual Install
+## Supported Clients
 
-**Cursor** — add to `~/.cursor/mcp.json`:
+| Client | Install |
+|--------|---------|
+| **Cursor** | `npx @dexterai/mcp install` or add to `~/.cursor/mcp.json` |
+| **Claude Code** | `claude mcp add dexter-x402 -- npx -y @dexterai/mcp@latest` |
+| **Codex** | `npx @dexterai/mcp install` or add to `~/.codex/config.toml` |
+| **VS Code** | `npx @dexterai/mcp install` |
+| **Windsurf** | `npx @dexterai/mcp install` |
+| **Gemini CLI** | `npx @dexterai/mcp install` |
+
+### Manual Config
+
+**Cursor** — `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -27,13 +38,7 @@ Supports: **Cursor**, **Claude Code**, **Codex**, **VS Code**, **Windsurf**, **G
 }
 ```
 
-**Claude Code:**
-
-```bash
-claude mcp add dexter-x402 -- npx -y @dexterai/mcp@latest
-```
-
-**Codex** — add to `~/.codex/config.toml`:
+**Codex** — `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.dexter-x402]
@@ -41,42 +46,105 @@ command = "npx"
 args = ["-y", "@dexterai/mcp@latest"]
 ```
 
-## How It Works
+## Tools
+
+### `x402_search`
+
+Search the Dexter marketplace for paid API resources. Returns pricing, quality scores, verification status, and call volume.
+
+```
+Agent: "Find me an image generation API"
+→ x402_search("image generation")
+→ Image Model - Seedream-4.5 — $0.08/call — verified — 44 calls
+```
+
+**Parameters:**
 
-On first run, a Solana wallet is created at `~/.dexterai-mcp/wallet.json`. Deposit USDC to the wallet address and the MCP handles payments automatically.
+| Param | Type | Description |
+|-------|------|-------------|
+| `query` | string | Search term |
+| `category` | string | Filter: "AI", "DeFi", "Data", "Tools", etc. |
+| `network` | string | Filter: "solana", "base", "polygon" |
+| `maxPriceUsdc` | number | Max price per call |
+| `verifiedOnly` | boolean | Only quality-checked endpoints |
+| `sort` | string | "relevance", "quality_score", "settlements", "volume", "recent" |
+| `limit` | number | Max results (1-50, default 20) |
 
-### Tools
+### `x402_fetch`
+
+Call any x402-protected API with automatic payment. Detects 402, signs the payment with your local wallet, and returns the API response.
+
+```
+Agent: "Get a Jupiter DEX quote for 1 SOL to USDC"
+→ x402_fetch("https://x402.dexter.cash/api/jupiter/quote?inputMint=So11...&outputMint=EPjF...&amount=1000000000")
+→ Pays $0.05 USDC, returns full quote with route plan
+```
+
+Works with any x402 endpoint, not just Dexter's. We tested with third-party sellers (Xona Agent, Corbits, etc.) and payment goes through identically.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `url` | string | The x402 resource URL |
+| `method` | string | GET, POST, PUT, DELETE (default: GET) |
+| `body` | string | JSON request body for POST/PUT |
+
+**Response includes:**
+
+```json
+{
+  "status": 200,
+  "data": { "...API response..." },
+  "payment": {
+    "settled": true,
+    "details": {
+      "transaction": "Djo6aA9SXFx...",
+      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+      "payer": "2SB3VTnjrct9ayYCsQ4Fi5C5vNVpwL8X8RYUQoaPNZGh"
+    }
+  }
+}
+```
 
-| Tool | Description |
-|------|-------------|
-| `x402_search` | Search the Dexter marketplace for paid APIs |
-| `x402_fetch` | Call any x402 API with automatic payment |
-| `x402_check` | Preview endpoint pricing without paying |
-| `x402_wallet` | Show wallet address and USDC balance |
+### `x402_check`
 
-### Example
+Preview endpoint pricing without making a payment. Probes the URL and returns payment requirements.
 
 ```
-Agent: "Find me a Jupiter DEX quote API"
-→ x402_search("jupiter quote")
-→ Returns: Jupiter DEX Quote — $0.05/call — verified
+Agent: "How much does this API cost?"
+→ x402_check("https://x402.dexter.cash/api/v2-test", method: "POST")
+→ $0.01 USDC on Solana, or $0.01 USDC on Base
+```
+
+### `x402_wallet`
 
-Agent: "Get a quote for 1 SOL → USDC"
-→ x402_fetch("https://x402.dexter.cash/api/jupiter/quote?inputMint=So1...&outputMint=EPjF...&amount=1000000000")
-→ Pays $0.05 USDC automatically, returns the quote
+Show the wallet address, USDC balance, and deposit instructions.
+
+```json
+{
+  "address": "2SB3VTnjrct9ayYCsQ4Fi5C5vNVpwL8X8RYUQoaPNZGh",
+  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  "balances": { "sol": 0, "usdc": 0.94 }
+}
 ```
 
 ## CLI
 
+Every tool is also available as a CLI command:
+
 ```bash
-# Show wallet address and balance
+# Create wallet and show address + balance
 npx @dexterai/mcp wallet
 
 # Search the marketplace
 npx @dexterai/mcp search "token analysis"
 
-# Call an x402 endpoint (auto-pays)
-npx @dexterai/mcp fetch "https://x402.dexter.cash/api/jupiter/quote?inputMint=So11...&amount=1000000000"
+# Pay for and call an x402 endpoint
+npx @dexterai/mcp fetch "https://x402.dexter.cash/api/jupiter/quote?inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1000000000"
+
+# POST with body
+npx @dexterai/mcp fetch "https://api.xona-agent.com/image-model/seedream-4.5" --method POST --body '{"prompt":"a robot painting"}'
 
 # Check pricing without paying
 npx @dexterai/mcp fetch "https://x402.dexter.cash/api/v2-test" --method POST
@@ -84,21 +152,67 @@ npx @dexterai/mcp fetch "https://x402.dexter.cash/api/v2-test" --method POST
 
 ## Wallet
 
-The wallet is a standard Solana keypair stored at `~/.dexterai-mcp/wallet.json` with `600` permissions. You own the key — it never leaves your machine.
+A standard Solana keypair stored at `~/.dexterai-mcp/wallet.json` with `600` permissions. The key never leaves your machine.
 
-Override with environment variable:
+**Override with environment variable:**
 
 ```bash
 export DEXTER_PRIVATE_KEY="your-base58-private-key"
 ```
 
-## Multi-Chain
+Or use an existing key:
+
+```bash
+export SOLANA_PRIVATE_KEY="your-base58-private-key"
+```
+
+Both work. The env var takes priority over the wallet file.
+
+## Chains
+
+Supports Solana and EVM chains through the [`@dexterai/x402`](https://www.npmjs.com/package/@dexterai/x402) SDK:
+
+| Chain | Network ID |
+|-------|------------|
+| Solana | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |
+| Base | `eip155:8453` |
+| Polygon | `eip155:137` |
+| Arbitrum | `eip155:42161` |
+| Optimism | `eip155:10` |
+| Avalanche | `eip155:43114` |
+| SKALE Europa | `eip155:2046399126` |
+
+The MCP auto-detects which chain a 402 response requires and uses the appropriate signing method.
+
+## How It Works
 
-Supports Solana and EVM chains (Base, Polygon, Arbitrum, Optimism, Avalanche, SKALE Europa) through the `@dexterai/x402` SDK. The MCP auto-detects which chain a 402 requires and uses the appropriate wallet.
+1. Your agent calls `x402_search` to find a paid API
+2. Your agent calls `x402_fetch` with the URL
+3. The MCP hits the endpoint, gets a 402 Payment Required response
+4. The MCP reads the payment requirements (price, chain, recipient)
+5. The MCP builds and signs a payment transaction using your local wallet
+6. The MCP retries the request with the payment proof
+7. The endpoint validates payment via the Dexter facilitator
+8. Your agent gets the API response
+
+All of this happens in one tool call. The agent never touches crypto.
+
+## What is x402?
+
+[x402](https://x402.org) is an open standard for machine-to-machine payments over HTTP. When an API returns `402 Payment Required`, it includes payment instructions. The client pays (usually USDC on Solana or Base), and the API delivers the response.
+
+Dexter operates the most-used x402 facilitator, processing millions of settlements. This MCP package connects your AI agent to that infrastructure.
 
 ## Links
 
-- **Marketplace:** https://dexter.cash/marketplace
-- **Facilitator:** https://x402.dexter.cash
-- **SDK:** https://www.npmjs.com/package/@dexterai/x402
+- **Dexter:** [dexter.cash](https://dexter.cash)
+- **Marketplace:** [dexter.cash/marketplace](https://dexter.cash/marketplace)
+- **Facilitator:** [x402.dexter.cash](https://x402.dexter.cash)
+- **SDK:** [@dexterai/x402](https://www.npmjs.com/package/@dexterai/x402)
+- **x402 Protocol:** [x402.org](https://x402.org)
 - **Twitter:** [@dexteraisol](https://twitter.com/dexteraisol)
+- **Telegram:** [t.me/dexterdao](https://t.me/dexterdao)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "x402 gateway for AI agents — search, pay, and call any x402 API through Dexter",
   "type": "module",
   "main": "dist/index.js",