x402 Data API Docs - How to Query x402 Payment Data

Learn how to query x402 payment data using GraphQL APIs. This comprehensive guide shows you how to access payment transactions, monitor server activity in real-time, and analyze payment analytics across multiple blockchain networks. The examples in this guide use Base network, but x402 protocol supports multiple chains.

What is x402 API?

The x402 API provides programmatic access to x402 protocol payment data through GraphQL queries. You can query payment transactions, track server activity, monitor real-time payments, and analyze payment analytics directly from the blockchain using Bitquery's streaming data platform.

x402 Overview

x402 is a decentralized payment protocol that enables pay-per-use API access on blockchain networks. It allows developers to monetize APIs and services by accepting cryptocurrency payments directly, eliminating the need for traditional subscription models or credit card processing. The protocol operates on multiple blockchain networks (including Base) and uses smart contracts to facilitate automatic payment verification and settlement between clients, servers, and facilitators.

How x402 Works?

x402 operates on a three-party architecture consisting of clients (API consumers), servers (API providers), and facilitators (payment processors). When a client wants to use a paid API service, they initiate a payment transaction on the blockchain. The facilitator validates the payment and notifies the server, which then processes the API request. The server verifies the payment payload embedded in the request headers before delivering the service. This creates a trustless system where payments are verified on-chain before service delivery, ensuring both parties fulfill their obligations without requiring intermediaries. All payment transactions are recorded on the blockchain and can be queried using GraphQL transfer queries for the respective network.

Various Actors in x402

The x402 ecosystem consists of three main actors:

Clients: Users or applications that consume paid API services. They initiate payment transactions and include payment payloads in their API requests.
Servers: API providers who offer services for payment. They verify payment payloads and deliver services after confirming valid payments on-chain. Server addresses can be tracked using transfer queries.
Facilitators: Payment processors that validate transactions, monitor the blockchain for payments, and notify servers when valid payments are detected. They help bridge the gap between on-chain payments and off-chain service delivery.

x402 Bazaar - Discover Services and Endpoints

The x402 Bazaar is a discovery service that allows you to find available x402-compatible APIs and services. You can query the Bazaar API to discover resources, view service metadata, check pricing, and understand API requirements.

Discovery API Endpoint

The x402 Bazaar discovery endpoint is available at:

https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources

This endpoint returns a paginated list of available x402 services with detailed information about each resource, including payment requirements, API schemas, performance metrics, and reliability scores.

Example API Response

When you query the x402 Bazaar discovery endpoint, you receive detailed information about each available service. Here's an example response structure:

{
  "accepts": [
    {
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "description": "Payment for token analysis service ($0.01)",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      },
      "maxAmountRequired": "10000",
      "maxTimeoutSeconds": 300,
      "mimeType": "application/json",
      "network": "base",
      "outputSchema": {
        "input": {
          "bodyFields": {
            "chain": {
              "default": "bsc",
              "description": "Blockchain name (bsc, solana, ethereum, etc.)",
              "required": false,
              "type": "string"
            },
            "language": {
              "default": "English",
              "description": "Output language (English, Chinese, Korean, etc.)",
              "required": false,
              "type": "string"
            },
            "token": {
              "description": "Token address or symbol (e.g. BTC, ETH, SOL, etc.)",
              "required": true,
              "type": "string"
            }
          },
          "bodyType": "json",
          "headerFields": {
            "X-PAYMENT": {
              "description": "Base64-encoded JSON PaymentPayload; automatically filled by x402scan",
              "required": false,
              "type": "string"
            }
          },
          "method": "POST",
          "type": "http"
        },
        "output": {
          "analysis": "object",
          "chain": "string",
          "created_at": "string",
          "language": "string",
          "status": "string",
          "token": "string",
          "workflow_run_id": "string|null"
        }
      },
      "payTo": "0x83240485b70e5c820e5f180533fc6156470cfd0e",
      "resource": "https://x402.lucyos.ai/x402/tools/analyze_token",
      "scheme": "exact"
    }
  ],
  "lastUpdated": "2025-11-27T12:57:44.059Z",
  "metadata": {
    "confidence": {
      "overallScore": 0.75,
      "performanceScore": 0.32,
      "recencyScore": 1,
      "reliabilityScore": 0.98,
      "volumeScore": 0.8
    },
    "errorAnalysis": {
      "abandonedFlows": 18,
      "apiErrors": 0,
      "delayedSettlements": 0,
      "facilitatorErrors": 0,
      "requestErrors": 0
    },
    "paymentAnalytics": {
      "averageDailyTransactions": 139,
      "base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913": 9730000,
      "totalTransactions": 973,
      "totalUniqueUsers": 942,
      "transactions24h": 973,
      "transactionsMonth": 973,
      "transactionsWeek": 973
    },
    "performance": {
      "avgLatencyMs": 2525,
      "maxLatencyMs": 18221,
      "minLatencyMs": 1076,
      "recentAvgLatencyMs": 2359
    },
    "reliability": {
      "apiSuccessRate": 0.98,
      "successfulSettlements": 973,
      "totalRequests": 991
    }
  },
  "resource": "x402.lucyos.ai/x402/tools/analyze_token",
  "type": "http",
  "x402Version": 1
}

Understanding the Response Structure

The response contains several key sections:

accepts: Array of payment configurations, including the asset (token), payment amount, network, and API endpoint details
payTo: The server's wallet address that receives payments
resource: The actual API endpoint URL
outputSchema: Defines the API's input requirements and expected output format
metadata: Contains performance metrics, reliability scores, payment analytics, and error analysis
confidence: Overall quality scores based on performance, recency, reliability, and transaction volume

Payment Payload and Verification

The x402 protocol uses a payment payload system to verify payments between clients and servers. When a client makes a payment, they include a Base64-encoded JSON payment payload in the X-PAYMENT header of their API request.

Payment Payload Structure

The payment payload typically contains:

Transaction hash of the payment
Payment amount
Recipient address (server)
Timestamp
Nonce or unique identifier

Verification Process

Client Side: The client initiates a payment transaction on the supported blockchain network, sending supported tokens (such as USDC) to the server's address. The client then encodes the payment details into a Base64 JSON payload.
Server Side: The server receives the API request with the X-PAYMENT header. It decodes the payload and verifies the payment by checking:
- The transaction exists on-chain (verifiable through transaction queries)
- The payment amount matches the required fee
- The recipient address matches the server's address
- The transaction is confirmed and not a double-spend
Facilitator Role: Facilitators monitor the blockchain for payment transactions using real-time subscriptions. When they detect a valid payment to a registered server, they notify the server, enabling faster service delivery without waiting for full blockchain confirmation.

This architecture ensures that servers only deliver services after verifying valid on-chain payments, creating a trustless pay-per-use system.

x402 Data API Queries

The following queries demonstrate how to query x402 payment data using Bitquery's GraphQL API. These queries help you monitor payments, track server activity, and analyze payment analytics. For more information on building queries, see our GraphQL query guide and filtering documentation.

Multi-Chain Support

x402 protocol supports multiple blockchain networks. The examples below use Base network, but you can adapt these queries for other supported chains by changing the network parameter.

Example x402 Server

For the following examples, we'll use this x402 server address:

Server Address: 0x83240485b70e5c820e5f180533fc6156470cfd0e

This server provides token analysis services and accepts USDC payments. The examples below use Base network, but the same query structure applies to other supported chains.

Listening to Latest Payments to a Specific Server

This query retrieves the most recent payments made to a specific x402 server. It's useful for monitoring server activity and tracking payment transactions.

You can run this query here.

query MyQuery {
  EVM(dataset: realtime, network: base) {
    Transfers(
      where: {Transfer: {Receiver: {in: ["0x83240485b70e5c820e5f180533fc6156470cfd0e"]}}}
      orderBy: {descending: Block_Number}
      limit: {count: 100}
    ) {
      Transaction {
        Hash
      }
      Transfer {
        Amount
        Sender
        Receiver
        Currency {
          Symbol
          Name
        }
      }
    }
  }
}

Query Explanation

dataset: realtime: Queries the most recent blockchain data. Learn more about dataset options
network: base: Specifies the network (Base in this example). Change this to query other supported chains (e.g., network: ethereum, network: bsc). See supported networks
Receiver: {in: [...]}: Filters transfers to the specific server address using GraphQL filters
orderBy: {descending: Block_Number}: Returns the most recent payments first. See sorting documentation
limit: {count: 100}: Retrieves up to 100 payment transactions. Check query limits

Real-Time Payment Monitoring with GraphQL WebSockets

You can monitor payments to a specific x402 server in real-time using GraphQL WebSocket subscriptions. This enables live tracking of payment activity without polling.

You can run this subscription here.

subscription {
  EVM(network: base) {
    Transfers(
      where: {Transfer: {Receiver: {in: ["0x83240485b70e5c820e5f180533fc6156470cfd0e"]}}}
    ) {
      Transaction {
        Hash
      }
      Transfer {
        Amount
        Sender
        Receiver
        Currency {
          Symbol
          Name
        }
      }
    }
  }
}

Subscription Explanation

subscription: Uses GraphQL subscription for real-time updates
EVM(network: base): Monitors the specified network (Base in this example). Change the network parameter to monitor other supported chains
Transfers: Listens for new transfer events matching the filter
The subscription will automatically push new payment transactions as they occur on-chain. Learn more about real-time subscriptions

Payment Analytics for Specific x402 Server

This query provides comprehensive payment analytics for a specific x402 server, including total volume, unique users, transaction counts, and time-based breakdowns.

You can run this query here.

query MyQuery {
  EVM(dataset: combined, network: base) {
    Transfers(
      where: {
        Block: {Time: {since_relative: {days_ago: 7}}}
        Transfer: {
          Currency: {SmartContract: {is: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}
          Receiver: {in: ["0x83240485b70e5c820e5f180533fc6156470cfd0e"]}
        }
      }
    ) {
      Transfer {
        Receiver
      }
      amount7days: sum(of: Transfer_Amount)
      amountInUSD7days: sum(of: Transfer_AmountInUSD)
      totalUniqueUsers7days: count(distinct: Transfer_Sender)
      totalTransactions7days: count(distinct: Transaction_Hash)
      transactions24h: count(
        distinct: Transaction_Hash
        if: {Block: {Time: {since_relative: {hours_ago: 24}}}}
      )
    }
  }
}

Query Explanation

dataset: combined: Queries both historical and real-time data. See dataset options
since_relative: {days_ago: 7}: Analyzes the last 7 days of payments using datetime filters
Currency: {SmartContract: {is: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}: Filters for USDC payments (this is the USDC contract address on Base; use the appropriate contract address for other networks). Learn about token transfer queries
sum(of: Transfer_Amount): Calculates total payment volume using GraphQL metrics
sum(of: Transfer_AmountInUSD): Calculates total volume in USD
count(distinct: Transfer_Sender): Counts unique users who made payments
count(distinct: Transaction_Hash): Counts total payment transactions
transactions24h: Conditional count for transactions in the last 24 hours using conditional metrics

Analytics Metrics Returned

amount7days: Total payment amount received in the last 7 days
amountInUSD7days: Total payment amount in USD equivalent
totalUniqueUsers7days: Number of unique users who made payments
totalTransactions7days: Total number of payment transactions
transactions24h: Number of transactions in the last 24 hours

Additional Use Cases

Monitor Multiple x402 Servers

You can monitor payments to multiple x402 servers by adding more addresses to the in array:

where: {
  Transfer: {
    Receiver: {
      in: [
        "0x83240485b70e5c820e5f180533fc6156470cfd0e",
        "0x45A33aC6DB4455460b364A1fc1aE8C489Bc644A7"
      ]
    }
  }
}

Filter by Payment Amount

To filter payments by minimum amount:

where: {
  Transfer: {
    Receiver: {in: ["0x83240485b70e5c820e5f180533fc6156470cfd0e"]}
    Amount: {gt: "10000"}  // Minimum 0.01 USDC (6 decimals)
  }
}

Time-Based Analysis

Analyze payments over different time periods:

where: {
  Block: {
    Time: {
      since: "2024-01-01T00:00:00Z"
      till: "2024-12-31T23:59:59Z"
    }
  }
}

x402 Queries on Solana

x402 protocol also operates on Solana network. The following queries demonstrate how to query x402 payment data on Solana using Bitquery's GraphQL API. Solana uses a different address format and query structure compared to EVM chains.

Example x402 Server on Solana

For the following Solana examples, we'll use this x402 server address:

Server Address: DevFFyNWxZPtYLpEjzUnN1PFc9Po6PH7eZCi9f3tTkTw

This is the Dexter • Crypto agent server address that accepts payments on Solana.

Latest Payment to x402 Server on Solana

This query retrieves the most recent payments made to a specific x402 server on Solana. It's useful for monitoring server activity and tracking payment transactions.

You can run this query here.

{
  Solana {
    Transfers(
      limit: {count: 100}
      orderBy: {descending: Block_Time}
      where: {Transfer: {Receiver: {Owner: {is: "DevFFyNWxZPtYLpEjzUnN1PFc9Po6PH7eZCi9f3tTkTw"}}}}
    ) {
      Transfer {
        Amount
        AmountInUSD
        Sender {
          Address
          Owner
        }
        Receiver {
          Address
          Owner
        }
        Currency {
          Symbol
          Name
          MintAddress
        }
      }
      Instruction {
        Program {
          Method
        }
      }
      Block {
        Time
      }
      Transaction {
        Signature
      }
    }
  }
}

Query Explanation

Solana: Specifies the Solana network schema
Receiver: {Owner: {is: "..."}}: Filters transfers to the specific server owner address (Solana uses owner addresses instead of contract addresses)
orderBy: {descending: Block_Time}: Returns the most recent payments first
limit: {count: 100}: Retrieves up to 100 payment transactions
AmountInUSD: Shows the payment amount in USD equivalent
Instruction: Provides details about the Solana program instruction that executed the transfer

Real-Time Payment Monitoring on Solana

You can monitor payments to a specific x402 server on Solana in real-time using GraphQL WebSocket subscriptions. This enables live tracking of payment activity without polling.

You can run this subscription here.

subscription {
  Solana {
    Transfers(
      where: {Transfer: {Receiver: {Owner: {is: "DevFFyNWxZPtYLpEjzUnN1PFc9Po6PH7eZCi9f3tTkTw"}}}}
    ) {
      Transfer {
        Amount
        AmountInUSD
        Sender {
          Address
          Owner
        }
        Receiver {
          Address
          Owner
        }
        Currency {
          Symbol
          Name
          MintAddress
        }
      }
      Instruction {
        Program {
          Method
        }
      }
      Block {
        Time
      }
      Transaction {
        Signature
      }
    }
  }
}

Subscription Explanation

subscription: Uses GraphQL subscription for real-time updates
Solana: Monitors the Solana network
Transfers: Listens for new transfer events matching the filter
The subscription will automatically push new payment transactions as they occur on-chain. Learn more about real-time subscriptions

Payment Analytics for x402 Server on Solana

This query provides comprehensive payment analytics for a specific x402 server on Solana, including total volume, unique users, and transaction counts.

Solana API Version

For complete transfer history on Solana, we use the v1 Solana API because v2 Solana API only shows transfers from the last 8 hours. The v1 API provides complete transfer history for comprehensive analytics.

You can run this query here.

{
  solana {
    transfers(
      date: {since: "2025-11-22"}
      receiverAddress: {is: "DevFFyNWxZPtYLpEjzUnN1PFc9Po6PH7eZCi9f3tTkTw"}
      currency: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
    ) {
      totalTransactions7days: count(uniq: signature)
      amount7days: amount(calculate: sum)
      totalUniqueUsers7days: count(uniq: sender_address)
      transactions24h: count(time: {since: "2025-11-28T00:00:00"})
    }
  }
}

Query Explanation

solana: Uses the v1 Solana API schema for complete historical data
date: {since: "2025-11-22"}: Analyzes payments since the specified date
receiverAddress: {is: "..."}: Filters for transfers to the specific server address
currency: {is: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}: Filters for USDC payments (USDC mint address on Solana)
count(uniq: signature): Counts unique transaction signatures
amount(calculate: sum): Calculates total payment volume
count(uniq: sender_address): Counts unique users who made payments
count(time: {since: "..."}): Conditional count for transactions in the last 24 hours

Analytics Metrics Returned

totalTransactions7days: Total number of payment transactions in the specified period
amount7days: Total payment amount received
totalUniqueUsers7days: Number of unique users who made payments
transactions24h: Number of transactions in the last 24 hours

Blockchain Networks - Overview of supported blockchain networks
Base Network Documentation - Complete guide to querying Base blockchain data
Solana Network Documentation - Complete guide to querying Solana blockchain data
Ethereum Network Documentation - Query Ethereum blockchain data
BSC Network Documentation - Query BSC blockchain data
GraphQL Query Guide - Learn how to build GraphQL queries
Real-time Subscriptions - Monitor blockchain data in real-time
Transfer API Documentation - Query ERC-20 token transfers
Solana Transfers - Query Solana token transfers
GraphQL Filters - Advanced filtering techniques
GraphQL Metrics - Aggregation and calculation functions
Datetime Queries - Time-based filtering and analysis
Getting Started Guide - Build your first query
WebSocket Subscriptions - Real-time data streaming

What is x402 API?​

x402 Overview​

How x402 Works?​

Various Actors in x402​

x402 Bazaar - Discover Services and Endpoints​

Discovery API Endpoint​

Example API Response​

Understanding the Response Structure​

Payment Payload and Verification​

Payment Payload Structure​

Verification Process​

x402 Data API Queries​

Example x402 Server​

Listening to Latest Payments to a Specific Server​

Query Explanation​

Real-Time Payment Monitoring with GraphQL WebSockets​

Subscription Explanation​

Payment Analytics for Specific x402 Server​

Query Explanation​

Analytics Metrics Returned​

Additional Use Cases​

Monitor Multiple x402 Servers​

Filter by Payment Amount​

Time-Based Analysis​

x402 Queries on Solana​

Example x402 Server on Solana​

Latest Payment to x402 Server on Solana​

Query Explanation​

Real-Time Payment Monitoring on Solana​

Subscription Explanation​

Payment Analytics for x402 Server on Solana​

Query Explanation​

Analytics Metrics Returned​

Related Documentation​

What is x402 API?

x402 Overview

How x402 Works?

Various Actors in x402

x402 Bazaar - Discover Services and Endpoints

Discovery API Endpoint

Example API Response

Understanding the Response Structure

Payment Payload and Verification

Payment Payload Structure

Verification Process

x402 Data API Queries

Example x402 Server

Listening to Latest Payments to a Specific Server

Query Explanation

Real-Time Payment Monitoring with GraphQL WebSockets

Subscription Explanation

Payment Analytics for Specific x402 Server

Query Explanation

Analytics Metrics Returned

Additional Use Cases

Monitor Multiple x402 Servers

Filter by Payment Amount

Time-Based Analysis

x402 Queries on Solana

Example x402 Server on Solana

Latest Payment to x402 Server on Solana

Query Explanation

Real-Time Payment Monitoring on Solana

Subscription Explanation

Payment Analytics for x402 Server on Solana

Query Explanation

Analytics Metrics Returned

Related Documentation