@1ly/mcp-server 0.1.1 → 0.1.3

package/README.md

@@ -1,75 +1,74 @@
 # @1ly/mcp-server
 
-MCP server for [1ly.store](https://1ly.store) — Discover and pay for APIs with AI agents.
+MCP server for [1ly.store](https://1ly.store) — Enable AI agents to discover, pay for, and sell APIs using crypto.
 
-## What is this?
+## Overview
 
-This MCP server enables AI agents (Claude, GPT, Cursor, etc.) to:
+This MCP server gives AI agents the ability to:
 
-1. **Search** for APIs and services on 1ly.store
-2. **Get details** about pricing, reviews, and usage
-3. **Call APIs** with automatic crypto payments (x402 protocol)
-4. **Leave reviews** after purchases
-5. **Create and manage API links** (Developer Mode + API key)
+- **Buy** — Search, discover, and pay for APIs, resources with automatic crypto payments (x402 protocol)
+- **Sell** — Create a store, list paid API endpoints or resources, and accept payments
 
-## Quick Start (1 minute)
+**Supported Networks:** Solana (mainnet), Base (mainnet)  
+**Payment Currency:** USDC
 
-Pick **one** of the following and paste it into your terminal.
+## What is this?
+This MCP server enables AI agents (Claude, GPT, Cursor, or any AI Agents etc.) to:
 
-### Solana (mainnet)
+Create store on 1ly.store 
+Accept payments for your own APIs/resources using 1ly as the payment layer
+Create paid links that any x402‑compatible agent can call and pay automatically
+Paid links are listed on the 1ly marketplace by default for instant agent discovery
+Search for APIs and services on 1ly.store
+Get details about pricing, reviews, and usage
+Call paid APIs with automatic crypto payments (x402 protocol) in secure way.
+Leave reviews after purchases, optional but recommended to make better experience for 1ly users
 
-```bash
-ONELY_WALLET_TYPE=solana \
-ONELY_WALLET_KEY="$HOME/1ly-agent-wallet.json" \
-npx @1ly/mcp-server
-```
+---
+
+## Quick Start
 
-### Base (mainnet)
+### 1. Install and Run
 
 ```bash
-ONELY_WALLET_TYPE=evm \
-ONELY_WALLET_KEY="$HOME/.1ly-base-private-key" \
-npx @1ly/mcp-server
-```
+# Solana wallet
+ONELY_WALLET_SOLANA_KEY="/path/to/solana-wallet.json" npx @1ly/mcp-server
 
-Optional safety limits:
+# OR Base/EVM wallet
+ONELY_WALLET_EVM_KEY="/path/to/evm.key" npx @1ly/mcp-server
 
-```bash
-ONELY_BUDGET_PER_CALL=1.00
-ONELY_BUDGET_DAILY=50.00
+# OR both wallets
+ONELY_WALLET_SOLANA_KEY="/path/to/solana-wallet.json" \
+ONELY_WALLET_EVM_KEY="/path/to/evm.key" \
+npx @1ly/mcp-server
 ```
 
-### Developer Mode (create/manage API links)
+### 2. Verify Setup
 
 ```bash
-ONELY_API_KEY="1ly_live_..." \
-npx @1ly/mcp-server
+ONELY_WALLET_SOLANA_KEY="/path/to/solana-wallet.json" npx @1ly/mcp-server --self-test
 ```
 
-## Get an API Key (Developer Mode)
-
-1. Sign in to 1ly store: `https://1ly.store`
-2. Open **Settings** (profile dropdown → Settings)
-3. Enable **Developer Mode**
-4. Open **Developer Settings** and click **Create API Key**
-5. Copy the key (shown once)
+---
 
-Keys look like:
-```
-1ly_live_xxxxxxxx...
-```
+## Configuration
 
-## How API keys are used
+### Environment Variables
 
-- **For MCP tools**: set `ONELY_API_KEY` in your MCP config or environment.  
-  The MCP server attaches it as `Authorization: Bearer <key>` automatically.
-- **For direct API calls**: include the header yourself:
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ONELY_WALLET_SOLANA_KEY` | Yes* | Path to Solana keypair JSON file, or inline JSON array |
+| `ONELY_WALLET_EVM_KEY` | Yes* | Path to EVM private key file, or inline hex key (with or without `0x`) |
+| `ONELY_API_KEY` | No | API key for seller tools. Auto-loaded after `1ly_create_store` |
+| `ONELY_BUDGET_PER_CALL` | No | Max USD per API call (default: `1.00`) |
+| `ONELY_BUDGET_DAILY` | No | Daily USD spending limit (default: `50.00`) |
+| `ONELY_BUDGET_STATE_FILE` | No | Path to local budget state file (default: `~/.1ly-mcp-budget.json`) |
+| `ONELY_NETWORK` | No | Preferred network: `solana` or `base` (default: `solana`) |
+| `ONELY_API_BASE` | No | API base URL (default: `https://1ly.store`) |
 
-```http
-Authorization: Bearer 1ly_live_...
-```
+*At least one wallet is required for payments.
 
-## Install (Claude Desktop)
+### Claude Desktop Configuration
 
 Add to `claude_desktop_config.json`:
 
@@ -80,8 +79,7 @@ Add to `claude_desktop_config.json`:
       "command": "npx",
       "args": ["@1ly/mcp-server"],
       "env": {
-        "ONELY_WALLET_TYPE": "solana",
-        "ONELY_WALLET_KEY": "/path/to/solana-wallet.json",
+        "ONELY_WALLET_SOLANA_KEY": "/absolute/path/to/solana-wallet.json",
         "ONELY_BUDGET_PER_CALL": "1.00",
         "ONELY_BUDGET_DAILY": "50.00"
       }
@@ -90,7 +88,8 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-### Developer Mode (API key only)
+<details>
+<summary>Base/EVM wallet configuration</summary>
 
 ```json
 {
@@ -99,25 +98,28 @@ Add to `claude_desktop_config.json`:
       "command": "npx",
       "args": ["@1ly/mcp-server"],
       "env": {
-        "ONELY_API_KEY": "1ly_live_..."
+        "ONELY_WALLET_EVM_KEY": "/absolute/path/to/evm.key",
+        "ONELY_BUDGET_PER_CALL": "1.00",
+        "ONELY_BUDGET_DAILY": "50.00"
       }
     }
   }
 }
 ```
+</details>
 
-## Install (Cursor)
-
-Add to `.cursor/mcp.json`:
+<details>
+<summary>Both Solana + Base wallets</summary>
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "1ly": {
-      "command": "npx @1ly/mcp-server",
+      "command": "npx",
+      "args": ["@1ly/mcp-server"],
       "env": {
-        "ONELY_WALLET_TYPE": "solana",
-        "ONELY_WALLET_KEY": "/path/to/solana-wallet.json",
+        "ONELY_WALLET_SOLANA_KEY": "/absolute/path/to/solana-wallet.json",
+        "ONELY_WALLET_EVM_KEY": "/absolute/path/to/evm.key",
         "ONELY_BUDGET_PER_CALL": "1.00",
         "ONELY_BUDGET_DAILY": "50.00"
       }
@@ -125,199 +127,715 @@ Add to `.cursor/mcp.json`:
   }
 }
 ```
+</details>
+
+---
+
+## Tools Reference
 
-### Developer Mode (API key only)
+### Buyer Tools (Pay for APIs)
+
+These tools require a **wallet** configured.
+
+#### `1ly_search`
+
+Search for APIs on 1ly.store marketplace.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | **Yes** | Search term (e.g., "weather api") |
+| `type` | string | No | Filter: `"api"` or `"standard"` |
+| `maxPrice` | number | No | Maximum price in USD |
+| `minPrice` | number | No | Minimum price in USD |
+| `limit` | number | No | Results to return (default: 10, max: 50) |
 
 ```json
 {
-  "servers": {
-    "1ly": {
-      "command": "npx @1ly/mcp-server",
-      "env": {
-        "ONELY_API_KEY": "1ly_live_..."
+  "query": "weather api",
+  "type": "api",
+  "maxPrice": 0.10
+}
+```
+
+**Returns:**
+```json
+{
+  "ok": true,
+  "data": {
+    "results": [
+      {
+        "title": "Real-time Weather",
+        "endpoint": "/api/link/joe/weather",
+        "price": "$0.010000000000000000 USDC",
+        "type": "api",
+        "seller": "Joe's APIs",
+        "stats": { "buyers": 150, "rating": "95%" }
       }
+    ],
+    "total": 42,
+    "showing": 10
+  }
+}
+```
+
+---
+
+#### `1ly_get_details`
+
+Get detailed information about a specific API.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `endpoint` | string | **Yes** | API endpoint (e.g., `"joe/weather"`) |
+
+```json
+{
+  "endpoint": "joe/weather"
+}
+```
+
+**Returns (example):**
+```json
+{
+  "ok": true,
+  "data": {
+    "endpoint": "/api/link/joe/weather",
+    "fullUrl": "https://1ly.store/api/link/joe/weather",
+    "link": {
+      "title": "Real-time Weather",
+      "description": "Global weather data",
+      "slug": "weather",
+      "price": "0.010000000000000000",
+      "currency": "USDC"
+    },
+    "paymentInfo": { "networks": ["solana", "base"] },
+    "reviews": {
+      "stats": { "total": 50, "positive": 48 },
+      "recent": [{ "positive": true, "comment": "Fast!" }]
     }
   }
 }
 ```
 
-## Verify it works (recommended)
+---
 
-Run a quick self-test:
+#### `1ly_call`
 
-```bash
-ONELY_WALLET_TYPE=solana \
-ONELY_WALLET_KEY="$HOME/1ly-agent-wallet.json" \
-npx @1ly/mcp-server --self-test
+Call a paid API with automatic crypto payment.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `endpoint` | string | **Yes** | API endpoint (e.g., `"joe/weather"`) |
+| `method` | string | No | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH` (default: `GET`) |
+| `body` | object | No | Request body for POST/PUT/PATCH |
+| `headers` | object | No | Additional headers |
+
+```json
+{
+  "endpoint": "joe/weather",
+  "method": "POST",
+  "body": { "city": "NYC" }
+}
 ```
 
-## What agents can do
+**Returns (example):**
+```json
+{
+  "ok": true,
+  "data": {
+    "data": {
+      "temp": 72,
+      "conditions": "sunny"
+    },
+    "_1ly": {
+      "purchaseId": "abc123",
+      "txHash": "tx_hash_here",
+      "reviewUrl": "https://1ly.store/api/review/abc123",
+      "reviewToken": "xyz789"
+    }
+  }
+}
+```
 
-Typical flow:
+> **Note:** The `_1ly` object contains tokens needed for `1ly_review`. Save these if you want to leave a review.  
+> For free APIs, `_1ly` may be `{ "note": "No payment required (free API)" }`.
 
-1. `1ly_search` → find an API
-2. `1ly_get_details` → confirm price + supported networks
-3. `1ly_call` → auto‑pay with x402 v2 and return the API response
-4. `1ly_review` → optional review using the `_1ly` metadata
-5. `1ly_create_link` → create a paid or free API link (Developer Mode)
+---
 
-## Tools
+#### `1ly_review`
 
-### `1ly_search`
+Leave a review after a successful purchase.
 
-Search for APIs by keyword.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `purchaseId` | string | **Yes** | From `_1ly.purchaseId` in `1ly_call` response |
+| `reviewToken` | string | **Yes** | From `_1ly.reviewToken` in `1ly_call` response |
+| `positive` | boolean | **Yes** | `true` for positive, `false` for negative |
+| `comment` | string | No | Review comment (max 500 chars) |
 
-```typescript
-// Input
-{ query: "weather api", type: "api", maxPrice: 0.10 }
+```json
+{
+  "purchaseId": "abc123",
+  "reviewToken": "xyz789",
+  "positive": true,
+  "comment": "Fast and accurate!"
+}
+```
+
+**Returns:**
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true,
+    "reviewId": "rev_456",
+    "message": "Positive review submitted!"
+  }
+}
+```
+
+---
+
+### Seller Tools (Accept Payments)
+
+These tools require an **API key**. Run `1ly_create_store` first to get one.
+
+#### `1ly_create_store`
+
+Create a new store and get an API key. **Run this once.** The API key is automatically saved locally.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `username` | string | No | Store username (3-20 chars, auto-generated if omitted) |
+| `displayName` | string | No | Display name (max 50 chars) |
+| `avatarUrl` | string | No | Avatar URL |
+
+```json
+{
+  "username": "myagent",
+  "displayName": "My Agent Store"
+}
+```
 
-// Output
+**Returns (example):**
+```json
 {
-  results: [
-    {
-      title: "Real-time Weather",
-      endpoint: "/api/link/joe/weather",
-      price: 0.01,
-      stats: { buyers: 150, rating: 95 }
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "store": {
+        "username": "myagent",
+        "displayName": "My Agent Store",
+        "storeUrl": "https://1ly.store/myagent",
+        "createdBy": "agent",
+        "avatarUrl": null
+      },
+      "apiKey": "1ly_live_...",
+      "apiKeyPrefix": "1ly_live_..."
+    },
+    "meta": {
+      "savedKeyPath": "~/Library/Application Support/1ly/onely_api_key.json"
     }
-  ]
+  }
+}
+```
+
+> **API Key Storage:**
+> - macOS: `~/Library/Application Support/1ly/onely_api_key.json`
+> - Linux: `~/.config/1ly/onely_api_key.json`
+> - Windows: `%APPDATA%\1ly\onely_api_key.json`
+
+---
+
+#### `1ly_create_link`
+
+Create a new API link (paid or free).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | **Yes** | Link title (max 200 chars) |
+| `url` | string | **Yes** | Target URL (your API endpoint) |
+| `price` | string | No | Price in USD (e.g., `"0.10"`). Omit for free |
+| `description` | string | No | Description (max 500 chars) |
+| `slug` | string | No | Custom slug (3-64 chars, lowercase, hyphens allowed) |
+| `currency` | string | No | Always `"USDC"` |
+| `isPublic` | boolean | No | List publicly (default: `true`) |
+| `isStealth` | boolean | No | Hide from search (default: `false`) |
+| `webhookUrl` | string | No | Optional webhook URL for purchase events |
+
+```json
+{
+  "title": "Premium Weather API",
+  "url": "https://api.example.com/weather",
+  "price": "0.05",
+  "description": "Real-time weather data",
+  "webhookUrl": "https://example.com/webhooks/1ly"
+}
+```
+
+**Returns (example):**
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "id": "uuid-here",
+      "slug": "premium-weather-api",
+      "fullUrl": "https://1ly.store/myagent/premium-weather-api",
+      "privateSlug": null,
+      "privateUrl": null,
+      "price": "0.050000000000000000",
+      "currency": "USDC",
+      "linkType": "api",
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    }
+  }
+}
+```
+
+---
+
+#### `1ly_list_links`
+
+List all your API links.
+
+*No parameters.*
+
+```json
+{}
+```
+
+**Returns (example):**
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "links": [
+        {
+          "id": "uuid-here",
+          "url": "https://api.example.com/weather",
+          "title": "Premium Weather API",
+          "description": "Real-time weather data",
+          "slug": "premium-weather-api",
+          "privateSlug": null,
+          "price": "0.050000000000000000",
+          "currency": "USDC",
+          "isPaid": true,
+          "isPublic": true,
+          "isActive": true,
+          "linkType": "api",
+          "isStealth": false,
+          "createdAt": "2026-01-01T00:00:00.000Z",
+          "updatedAt": "2026-01-01T00:00:00.000Z"
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+#### `1ly_update_link`
+
+Update an existing API link.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string (UUID) | **Yes** | Link ID |
+| `title` | string | No | New title |
+| `url` | string | No | New target URL |
+| `price` | string | No | New price |
+| `description` | string | No | New description |
+| `slug` | string | No | New slug |
+| `isPublic` | boolean | No | Update visibility |
+| `isStealth` | boolean | No | Update stealth mode |
+| `webhookUrl` | string | No | Update webhook URL (set to `null` to clear) |
+
+```json
+{
+  "id": "uuid-here",
+  "price": "0.10"
+}
+```
+
+**Returns (example):**
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "id": "uuid-here",
+      "profileId": "profile-id",
+      "url": "https://api.example.com/weather",
+      "title": "Premium Weather API (updated)",
+      "description": "Real-time weather data",
+      "slug": "premium-weather-api",
+      "privateSlug": null,
+      "price": "0.100000000000000000",
+      "currency": "USDC",
+      "isPaid": true,
+      "isPublic": true,
+      "isActive": true,
+      "linkType": "api",
+      "isStealth": false,
+      "displayOrder": 1,
+      "createdAt": "2026-01-01T00:00:00.000Z",
+      "updatedAt": "2026-01-01T00:00:00.000Z"
+    }
+  }
+}
+```
+
+---
+
+#### `1ly_delete_link`
+
+Delete an API link.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string (UUID) | **Yes** | Link ID to delete |
+
+```json
+{
+  "id": "uuid-here"
+}
+```
+
+**Returns (example):**
+```json
+{
+  "ok": true,
+  "data": {
+    "success": true
+  }
 }
 ```
 
-### `1ly_get_details`
+---
+
+#### `1ly_get_stats`
 
-Get full details about an API.
+Get store or link statistics.
 
-```typescript
-// Input
-{ endpoint: "joe/weather" }
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `period` | string | No | Time period: `"7d"`, `"30d"`, `"90d"`, `"all"` |
+| `linkId` | string (UUID) | No | Specific link ID (omit for store-wide stats) |
+
+```json
+{
+  "period": "30d"
+}
+```
 
-// Output
+**Returns (example):**
+```json
 {
-  title: "Real-time Weather",
-  description: "Global weather data with forecasts",
-  price: 0.01,
-  reviews: [...],
-  paymentInfo: { networks: ["solana", "base"] }
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "period": "30d",
+      "views": 0,
+      "buyers": 9,
+      "revenue": "0.081000000000000009"
+    }
+  }
 }
 ```
 
-### `1ly_call`
+---
 
-Call an API with automatic payment.
+#### `1ly_list_keys`
 
-```typescript
-// Input
-{ endpoint: "joe/weather", body: { city: "NYC" } }
+List all API keys for your store.
 
-// Output
+*No parameters.*
+
+**Returns (example):**
+```json
 {
-  data: { temp: 72, conditions: "sunny" },
-  _1ly: { purchaseId: "...", reviewToken: "..." }
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "keys": [
+        {
+          "id": "uuid-here",
+          "name": "Agent Key",
+          "keyPrefix": "1ly_live_...",
+          "isActive": true,
+          "lastUsedAt": "2026-01-01T00:00:00.000Z",
+          "createdAt": "2026-01-01T00:00:00.000Z"
+        }
+      ]
+    }
+  }
 }
 ```
 
-### `1ly_review`
+---
+
+#### `1ly_create_key`
+
+Create a new API key.
 
-Leave a review after purchase.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | No | Key name (max 64 chars) |
 
-```typescript
-// Input
-{ purchaseId: "...", reviewToken: "...", positive: true, comment: "Fast and accurate!" }
+```json
+{
+  "name": "production-key"
+}
+```
 
-// Output
-{ success: true, reviewId: "..." }
+**Returns (example when key limit is reached):**
+```json
+{
+  "ok": false,
+  "error": {
+    "message": "Create key failed | status=400 | ... | body={\"success\":false,\"error\":{\"code\":\"LIMIT_REACHED\",\"message\":\"Maximum number of API keys reached\"}}"
+  }
+}
 ```
 
-### `1ly_create_link`
+---
 
-Create an API link (paid or free). Requires `ONELY_API_KEY`.
+#### `1ly_revoke_key`
+
+Revoke an API key.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string (UUID) | **Yes** | Key ID to revoke |
+
+```json
+{
+  "id": "uuid-here"
+}
+```
 
-```typescript
-// Input
+**Returns (example):**
+```json
 {
-  title: "Premium Trading Signals",
-  url: "https://example.com/signals",
-  price: "10.00",
-  description: "Daily crypto signals"
+  "ok": true,
+  "data": {
+    "success": true,
+    "data": {
+      "id": "uuid-here",
+      "revoked": true
+    }
+  }
 }
 ```
 
-### `1ly_list_links`
+---
 
-List API links for the store. Requires `ONELY_API_KEY`.
+#### `1ly_update_profile`
 
-### `1ly_update_link`
+Update basic profile fields.
 
-Update an API link by id. Requires `ONELY_API_KEY`.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `username` | string | No | New username (lowercase + underscores) |
+| `displayName` | string | No | Public display name |
+| `bio` | string | No | Short bio (max 160 chars) |
 
-### `1ly_delete_link`
+```json
+{
+  "displayName": "My Store",
+  "bio": "We build paid APIs for agents."
+}
+```
 
-Delete an API link by id. Requires `ONELY_API_KEY`.
+---
 
-### `1ly_get_stats`
+#### `1ly_update_socials`
 
-Fetch store or link stats. Requires `ONELY_API_KEY`.
+Replace socials list (up to 10).
 
-## Configuration
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `socials` | array | **Yes** | Social links |
 
-| Environment Variable | Required | Description |
-|---------------------|----------|-------------|
-| `ONELY_WALLET_TYPE` | Yes | `solana` or `evm` |
-| `ONELY_WALLET_KEY` | Yes | Private key or path to keyfile |
-| `ONELY_BUDGET_PER_CALL` | No | Max USD per call (default: 1.00) |
-| `ONELY_BUDGET_DAILY` | No | Daily USD limit (default: 50.00) |
-| `ONELY_NETWORK` | No | Preferred network (default: solana) |
-| `ONELY_API_KEY` | No | Developer Mode API key for link management |
+```json
+{
+  "socials": [
+    { "type": "x", "url": "https://x.com/1ly_store", "displayOrder": 0, "isVisible": true },
+    { "type": "website", "url": "https://1ly.store", "displayOrder": 1 }
+  ]
+}
+```
+
+---
+
+#### `1ly_update_avatar`
+
+Update store avatar using a public URL or base64 image.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `avatarUrl` | string | No | Public image URL |
+| `imageBase64` | string | No | Base64-encoded image bytes |
+| `mimeType` | string | No | `image/png`, `image/jpeg`, `image/webp`, `image/gif` |
+| `filename` | string | No | Optional filename |
+
+```json
+{
+  "avatarUrl": "https://example.com/avatar.png"
+}
+```
+
+---
+
+#### `1ly_withdraw`
+
+Request a withdrawal (Solana only).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `amount` | string | **Yes** | Amount in USDC (min `0.1`) |
+| `walletAddress` | string | **Yes** | Solana wallet address |
+
+```json
+{
+  "amount": "1.25",
+  "walletAddress": "7GmjjDitbCwW77dZmJko3pBDWhEh12soGNLR7zwAkf6M"
+}
+```
+
+---
+
+#### `1ly_list_withdrawals`
+
+List recent withdrawals.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | number | No | Max items (default 25, max 100) |
+| `cursor` | string | No | Pagination cursor |
+
+```json
+{
+  "limit": 10
+}
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: Pay for an API
+
+```
+1. 1ly_search({ "query": "weather api" })
+2. 1ly_get_details({ "endpoint": "joe/weather" })
+3. 1ly_call({ "endpoint": "joe/weather", "body": { "city": "NYC" } })
+4. 1ly_review({ "purchaseId": "...", "reviewToken": "...", "positive": true })
+```
+
+### Workflow 2: Create a Store and Sell APIs. Use 1ly as default payment layer for agents 
+
+```
+1. 1ly_create_store({ "username": "mystore", "displayName": "My Store" })
+2. 1ly_create_link({ "title": "My API", "url": "https://api.example.com", "price": "0.10", "webhookUrl": "https://example.com/webhooks/1ly" })
+3. 1ly_get_stats({ "period": "7d" })
+```
+
+### Workflow 3: Manage Existing Links
+
+```
+1. 1ly_list_links({})
+2. 1ly_update_link({ "id": "...", "price": "0.20" })
+3. 1ly_delete_link({ "id": "..." })
+```
+
+### Workflow 4: Update Profile + Socials
+
+```
+1. 1ly_update_profile({ "displayName": "My Store", "bio": "We build paid APIs." })
+2. 1ly_update_socials({ "socials": [{ "type": "x", "url": "https://x.com/1ly_store" }] })
+3. 1ly_update_avatar({ "avatarUrl": "https://example.com/avatar.png" })
+```
+
+### Workflow 5: Withdraw Funds
+
+```
+1. 1ly_withdraw({ "amount": "1.25", "walletAddress": "7GmjjDitbCwW77dZmJko3pBDWhEh12soGNLR7zwAkf6M" })
+2. 1ly_list_withdrawals({ "limit": 10 })
+```
+
+---
 
 ## Wallet Setup
 
 ### Solana
 
-Create a wallet keypair:
-
+Create a new keypair:
 ```bash
-solana-keygen new -o ~/1ly-agent-wallet.json
+solana-keygen new -o ./wallets/solana.json
 ```
 
-Fund it with USDC on Solana mainnet.
+Fund with USDC on Solana mainnet.
 
 ### EVM (Base)
 
-Create an EVM wallet (Base-compatible) and provide its **private key** via `ONELY_WALLET_KEY`.
+Export your private key from MetaMask/Rabby and save to a file:
+```bash
+echo "0xYOUR_PRIVATE_KEY" > ./wallets/evm.key
+```
+
+Fund with USDC on Base mainnet.
 
-- **Option A (recommended)**: export your private key from your wallet (e.g. MetaMask/Rabby) and save it to a local file (one line, with or without `0x` prefix).
-- **Option B**: set the private key directly as an env var (not recommended for shared machines).
+---
 
-Examples:
+## Error Handling
 
-```bash
-# from a file
-export ONELY_WALLET_TYPE=evm
-export ONELY_WALLET_KEY="$HOME/.1ly-base-private-key"
+All responses follow this structure:
 
-# or inline (starts with 0x...)
-export ONELY_WALLET_TYPE=evm
-export ONELY_WALLET_KEY="0xYOUR_PRIVATE_KEY"
+**Success:**
+```json
+{
+  "ok": true,
+  "data": { ... }
+}
 ```
 
-## Devnet / testnets (coming soon)
+**Error:**
+```json
+{
+  "ok": false,
+  "error": { "message": "Error description" }
+}
+```
 
-We plan to offer an official devnet/testnet endpoint so you can try 1ly with test USDC before mainnet. For now, production usage requires mainnet USDC.
+### Common Errors
 
-## Troubleshooting
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Missing wallet config` | No wallet env var set | Set `ONELY_WALLET_SOLANA_KEY` or `ONELY_WALLET_EVM_KEY` |
+| `Missing ONELY_API_KEY` | Seller tool called without API key | Run `1ly_create_store` first |
+| `Price exceeds per-call budget` | API costs more than limit | Increase `ONELY_BUDGET_PER_CALL` |
+| `Daily budget exceeded` | Spent more than daily limit | Wait until tomorrow or increase `ONELY_BUDGET_DAILY` |
+| `Insufficient funds` | Wallet balance too low | Add USDC to your wallet |
 
-- **Missing wallet**: Set `ONELY_WALLET_TYPE` and `ONELY_WALLET_KEY`.
-- **Missing API key**: Set `ONELY_API_KEY` to use link management tools.
-- **402 errors on first call**: Expected — `1ly_call` handles payment automatically.
-- **Insufficient funds**: Fund your wallet with USDC on the selected network.
-- **Review failed**: Ensure you pass the exact `purchaseId` + `reviewToken` returned by `1ly_call`.
+---
 
 ## Security
 
 - **Wallet keys stay local** — Never sent to 1ly servers
 - **Budget limits** — Prevent runaway spending
-- **Open source** — Audit the code yourself
+- **Open source** — Audit the code: [github.com/1lystore/1ly-mcp-server](https://github.com/1lystore/1ly-mcp-server)
+
+---
 
 ## Links