x402 Support

Access Quicksilver data sources without registration using x402 micropayments. Pay only for successful queries—no subscriptions.

Integration Options

Quicksilver provides two ways to access data via x402:

1. MCP Server (Recommended) — Zero-code integration for AI agents and MCP clients
2. Direct HTTP API — For custom integrations and non-MCP applications

Both approaches use the same underlying x402-enabled endpoints and pricing model.

Prerequisites

• USDC on IoTeX Network: Required for paid queries (free operations need no USDC)
  • Get USDC via IoTeX Hub or bridge from other networks
• Private Key: For signing x402 payment transactions
  • No gas (IOTX) required—the x402 facilitator covers all gas fees

Using the MCP Server (Recommended)

The Quicksilver MCP Server provides zero-code integration for AI agents, Cursor IDE, Claude Desktop, and other MCP clients. Payment signing and x402 protocol handling are automatic.

NPM Package: quicksilver-mcp

Installation

The MCP server requires Node.js 20 or higher. Verify your version:

node --version

Install from the Node.js website if needed.

Configuration

Add to your MCP client configuration (e.g., claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "quicksilver": {
      "command": "npx",
      "args": ["-y", "quicksilver-mcp@latest"],
      "env": {
        "RESOURCE_SERVER_URL": "https://data.iotex.ai/",
        "PRIVATE_KEY": "0x122345689....."
      }
    }
  }
}

Security: Replace PRIVATE_KEY with your actual private key. Never commit credentials to version control.

Available MCP Tools

The server provides three tools that interact with Quicksilver's x402 endpoints:

1. list-available-sources — List all data sources (free)
2. get-source-schema — Get schema and query parameters for a source (free)
3. query-source — Execute paid query via x402 (automatic payment handling)

The MCP server abstracts the x402 payment flow—simply call the tools and the server handles signing, verification, and settlement.

Direct HTTP API

For custom integrations outside MCP, Quicksilver exposes three x402-enabled HTTP endpoints:

Quick Example

List sources:

curl https://data.iotex.ai/api/x402/sources

Execute paid query (requires X-PAYMENT header):

curl -X POST https://data.iotex.ai/api/x402/sources/{sourceId}/query \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <signed-payment-payload>" \
  -d '{
    "entity": "currentconditions",
    "params": {
      "limit": 10,
      "where": { "city": "San Francisco" }
    }
  }'

Payment Integration

Use the x402-fetch package for automatic payment signing:

npm install x402-fetch viem

Example:

import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

const response = await fetchWithPayment(
  `https://data.iotex.ai/api/x402/sources/${sourceId}/query`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      entity: "currentconditions",
      params: { limit: 10, where: { city: "San Francisco" } }
    })
  }
);

const data = await response.json();
console.log(data);

For full x402 protocol details, see the x402 documentation.

API Endpoints Reference

GET /api/x402/sources

List all available data sources.

Response:

{
  "sources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "airvisual",
      "displayName": "AirVisual",
      "description": "Real-time air quality data",
      "x402": { "price_per_query": 0.001 }
    }
  ],
  "count": 1,
  "_meta": {
    "pricing": {
      "basePrice": 0.001,
      "currency": "USDC",
      "network": "iotex"
    }
  }
}

GET /api/x402/sources/{sourceId}

Get schema and query parameters for a specific source.

Response:

{
  "sourceId": "550e8400-...",
  "name": "airvisual",
  "schema": {
    "entities": [
      {
        "name": "CurrentConditions",
        "fields": { "city": "string", "aqi": "number" },
        "exampleQuery": {
          "entity": "currentconditions",
          "params": { "where": { "city": "San Francisco" }, "limit": 10 }
        }
      }
    ],
    "queryParameters": {
      "limit": { "type": "number", "optional": true, "default": 100 },
      "offset": { "type": "number", "optional": true, "default": 0 },
      "where": { "type": "object", "optional": true }
    }
  },
  "x402": { "price_per_query": 0.001 }
}

POST /api/x402/sources/{sourceId}/query

Execute a paid query. Requires X-PAYMENT header with signed x402 payment payload.

Success (200):

{
  "data": [
    { "city": "San Francisco", "country": "USA", "aqi": 45 }
  ]
}

Includes X-PAYMENT-RESPONSE header with settlement receipt.

Payment Required (402):

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "iotex",
      "maxAmountRequired": "1000",
      "currency": "USDC"
    }
  ]
}

Query Failed:

Payment is not settled if the query fails after verification. Response includes X-PAYMENT-STATUS: verified_not_settled.

Resources

• Quicksilver MCP Package — Official MCP server on npm
• IoTeX Hub — Get USDC on IoTeX network
• Model Context Protocol — MCP documentation
• x402 Protocol — x402 ecosystem homepage