Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions website/src/pages/en/subgraphs/tooling/x402-payments.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ The Graph's x402 Subgraph endpoints enable:
- **Per-query access** to any Subgraph published on The Graph Network
- **USDC payments** on Base (mainnet) and Base Sepolia (testnet)
- **No API keys, accounts, or sessions**: payment and access happen in a single HTTP round trip
- **Compatible with any x402 client**, with first-class support via `@graphprotocol/client-x402`
- **x402 v2 payments** using the `exact` scheme, with first-class support via `@graphprotocol/client-x402`

The existing API-key endpoints continue to work unchanged with x402 is an additional access path under `/api/x402/...`.
The existing API-key endpoints continue to work unchanged. x402 is an additional access path under `/api/x402/...`.

## How It Works

Expand All @@ -25,6 +25,8 @@ The existing API-key endpoints continue to work unchanged with x402 is an additi
3. The client signs a USDC payment payload and retries the request with the payment header.
4. The Gateway verifies the payment via a facilitator and returns the query result.

> **Protocol version:** The Gateway implements **x402 v2**. Send the signed payment payload in a `Payment-Signature` header (base64-encoded JSON containing `x402Version`, `accepted`, and `payload`). x402 v1 clients that send only `X-PAYMENT` receive `402 Payment-Signature header is required`, even after signing. Use a v2-compatible client such as `@graphprotocol/client-x402`, or upgrade your SDK.

## Network Environments

| Environment | Base URL | Payment Network | USDC Token Address |
Expand Down Expand Up @@ -64,6 +66,34 @@ x402 is well suited to:

For sustained, high-volume application use, the existing API-key flow remains the recommended path.

## Caveats

### Payment applies even when no Indexer is serving the Subgraph

A valid `subgraph_id` or `deployment_id` does not guarantee that any Indexer is currently allocated to it. When no Indexer is serving the deployment, the Gateway responds with `200 OK` and this payload:

```json
{ "errors": [{ "message": "subgraph not found: no allocations" }] }
```

The USDC payment is still settled, and there is no refund. To avoid paying for a deployment that no Indexer is serving, check for active allocations in the [Network Subgraph](https://thegraph.com/explorer/subgraphs/DZz4kDTdmzWLWsV373w2bSmoar3umKKH9y82SUKr5qmp?view=Query&chain=arbitrum-one) before paying. Use the deployment ID (`Qm...`) as `ipfsHash`:

```graphql
{
subgraphDeployments(where: { ipfsHash: "<DEPLOYMENT_ID>" }) {
indexerAllocations(where: { activeForIndexer_not: null }, first: 1) {
id
}
}
}
```

If `indexerAllocations` is empty, or no deployment is returned, no Indexer is serving it and paying will return the error above. Agents that discover Subgraphs automatically should treat a deployment with no active allocations as unservable, and either skip it or surface a warning.

### Errors still cost USDC

Any response from the Gateway that includes a `Payment-Response` header has been settled onchain. This includes responses that contain GraphQL `errors`, such as a bad query shape, missing fields, a schema mismatch, or "no allocations". Validate your query against the Subgraph's schema before paying, for example with a cached schema or the [Subgraph MCP](/subgraphs/tooling/subgraph-mcp/introduction/).

## Minimal Examples

### Using API Key
Expand All @@ -77,7 +107,7 @@ curl -X POST https://gateway.thegraph.com/api/subgraphs/id/5zvR82QoaXYFyDEKLZ9t6

### Using x402 Payment

Any x402 tooling that supports exact scheme will work with the gateway's x402 endpoints. We recommend to use the official Graph x402 client:
Use an x402 v2 client that supports the `exact` payment scheme on the gateway's payment network. We recommend the official Graph x402 client.

```bash
npm install @graphprotocol/client-x402
Expand Down
Loading