Protocol Reference

This page documents the full x402 protocol specification, including HTTP headers, payload formats, facilitator API endpoints, and error codes.

Payment Requirements (402 Response)

When a server endpoint requires payment, it responds with HTTP status 402 Payment Required. The response body contains the payment requirements that the client must satisfy.

HTTP Status

HTTP/1.1 402 Payment Required

Response Body

Field	Type	Description
`x402Version`	`number`	The x402 protocol version. Currently `1`.
`error`	`string`	A human-readable description of why payment is required.
`accepts`	`object[]`	An array of accepted payment options. The client can choose any one.

`accepts[]` Object

Each entry in the accepts array describes one acceptable payment method:

Field	Type	Description
`scheme`	`string`	The payment scheme identifier (e.g., `"exact"`).
`network`	`string`	The blockchain network (e.g., `"solana"`, `"solana-devnet"`).
`maxAmountRequired`	`string`	The maximum payment amount in the token's smallest unit (e.g., USDC has 6 decimals, so `"100000"` = 0.10 USDC).
`asset`	`string`	The token mint address or contract address of the payment asset.
`payTo`	`string`	The recipient wallet address that should receive the payment.
`resource`	`string`	The URL path of the resource being purchased.
`description`	`string`	A human-readable description of what the payment is for.
`mimeType`	`string`	The MIME type of the resource that will be returned after payment.
`outputSchema`	`object \| null`	An optional JSON Schema describing the structure of the response body.
`maxTimeoutSeconds`	`number`	The maximum number of seconds the server will wait for payment settlement.
`extra`	`object \| null`	Optional additional metadata specific to the payment scheme or network.

Example 402 Response

json

{
  "x402Version": 1,
  "error": "Payment required to access this resource.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "100000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "9aUn5swQzUTRanaaTwmszxiv89cvFwUCjEBv1vZCoT1u",
      "resource": "/api/premium-data",
      "description": "Access to premium data endpoint",
      "mimeType": "application/json",
      "outputSchema": null,
      "maxTimeoutSeconds": 60,
      "extra": null
    }
  ]
}

Payment Proof (X-PAYMENT Header)

After receiving a 402 response, the client constructs a payment proof and includes it in the X-PAYMENT header when retrying the request.

Format

The X-PAYMENT header value is a Base64-encoded JSON string with the following structure:

Field	Type	Description
`x402Version`	`number`	The x402 protocol version. Must match the version in the 402 response.
`scheme`	`string`	The payment scheme being used (e.g., `"exact"`).
`network`	`string`	The blockchain network (e.g., `"solana"`).
`payload`	`object`	The scheme-specific payment payload.

Solana Payload (Exact Scheme)

For the exact scheme on Solana, the payload object contains:

Field	Type	Description
`transaction`	`string`	A Base64-encoded partially-signed Solana transaction. The client signs the transaction as the payer, and the facilitator co-signs and submits it.

Example X-PAYMENT Header Value (Before Base64 Encoding)

json

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana",
  "payload": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
  }
}

Example Request with Payment

GET /api/premium-data HTTP/1.1
Host: example.com
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLn0=

Settlement Response (X-PAYMENT-RESPONSE Header)

After the server verifies and settles a payment, the response includes the X-PAYMENT-RESPONSE header with settlement details.

Fields

Field	Type	Description
`success`	`boolean`	Whether the payment was successfully settled.
`errorReason`	`string \| null`	A description of why the payment failed, or `null` if successful.
`transaction`	`string`	The on-chain transaction signature or hash.
`network`	`string`	The network the transaction was settled on (e.g., `"solana"`).
`payer`	`string`	The wallet address of the payer.

Example X-PAYMENT-RESPONSE Header Value

json

{
  "success": true,
  "errorReason": null,
  "transaction": "5UfDuX7hXrPtMGBb8efPkLszrgMfCnWdAhAkQbpSTmvHBMDy3UY...",
  "network": "solana",
  "payer": "7vto3C4YGhBrFsxVBu8TNaEL1gCDgMJwqBn2CnAFaJE2"
}

HTTP Status Codes

Status Code	Meaning	Description
`200`	Success	Payment was verified and settled. The response body contains the requested resource. The `X-PAYMENT-RESPONSE` header contains settlement details.
`402`	Payment Required	The resource requires payment. The response body contains payment requirements.
`400`	Bad Request	The payment payload is invalid, malformed, or does not meet the server's requirements.
`500`	Server Error	An unexpected error occurred during verification or settlement.

Facilitator API

The facilitator exposes HTTP endpoints for verifying and settling payments. The SVM Facilitator is hosted at https://facilitator.svmacc.tech.

`POST /verify`

Validates a payment payload without submitting it on-chain.

Request:

json

{
  "payload": "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLn0=",
  "requirements": {
    "scheme": "exact",
    "network": "solana",
    "maxAmountRequired": "100000",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "9aUn5swQzUTRanaaTwmszxiv89cvFwUCjEBv1vZCoT1u",
    "resource": "/api/premium-data",
    "description": "Access to premium data endpoint",
    "mimeType": "application/json",
    "outputSchema": null,
    "maxTimeoutSeconds": 60,
    "extra": null
  }
}

Response (success):

json

{
  "isValid": true,
  "invalidReason": null,
  "payer": "7vto3C4YGhBrFsxVBu8TNaEL1gCDgMJwqBn2CnAFaJE2"
}

Response (failure):

json

{
  "isValid": false,
  "invalidReason": "insufficient_funds",
  "payer": "7vto3C4YGhBrFsxVBu8TNaEL1gCDgMJwqBn2CnAFaJE2"
}

`POST /settle`

Submits a verified payment to the Solana network for on-chain settlement.

Request:

json

{
  "payload": "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLn0=",
  "requirements": {
    "scheme": "exact",
    "network": "solana",
    "maxAmountRequired": "100000",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "9aUn5swQzUTRanaaTwmszxiv89cvFwUCjEBv1vZCoT1u",
    "resource": "/api/premium-data",
    "description": "Access to premium data endpoint",
    "mimeType": "application/json",
    "outputSchema": null,
    "maxTimeoutSeconds": 60,
    "extra": null
  }
}

Response (success):

json

{
  "success": true,
  "errorReason": null,
  "transaction": "5UfDuX7hXrPtMGBb8efPkLszrgMfCnWdAhAkQbpSTmvHBMDy3UY...",
  "network": "solana",
  "payer": "7vto3C4YGhBrFsxVBu8TNaEL1gCDgMJwqBn2CnAFaJE2"
}

Response (failure):

json

{
  "success": false,
  "errorReason": "insufficient_funds",
  "transaction": null,
  "network": "solana",
  "payer": "7vto3C4YGhBrFsxVBu8TNaEL1gCDgMJwqBn2CnAFaJE2"
}

`GET /supported`

Returns all supported payment schemes, networks, and tokens.

Response:

json

{
  "x402Version": 1,
  "kinds": [
    {
      "scheme": "exact",
      "network": "solana",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    },
    {
      "scheme": "exact",
      "network": "solana-devnet",
      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"
    }
  ]
}

Error Codes

The following error codes may appear in the invalidReason field of a verify response or the errorReason field of a settle response.

General Error Codes

Error Code	Description
`insufficient_funds`	The payer does not have enough of the required token to cover the payment amount.
`invalid_network`	The specified network is not supported by the facilitator.
`invalid_payload`	The payment payload is malformed or cannot be decoded.
`invalid_scheme`	The specified payment scheme is not supported.
`invalid_x402_version`	The x402 protocol version in the payload does not match a supported version.
`invalid_transaction_state`	The transaction is in an invalid state (e.g., already executed, expired, or has an invalid blockhash).
`unexpected_verify_error`	An unexpected error occurred during payment verification.
`unexpected_settle_error`	An unexpected error occurred during on-chain settlement.

Solana-Specific Error Codes

Error Code	Description
`invalid_exact_svm_payload_transaction_instructions_length`	The Solana transaction contains an unexpected number of instructions. The facilitator expects a specific instruction layout for the exact payment scheme, and the submitted transaction does not match.

Next Steps

See the Facilitator page for details on the SVM Facilitator.
See Supported Networks for available networks and tokens.
See the Quickstart to start building with x402.

Protocol Reference ​

Payment Requirements (402 Response) ​

HTTP Status ​

Response Body ​

accepts[] Object ​

Example 402 Response ​

Payment Proof (X-PAYMENT Header) ​

Format ​

Solana Payload (Exact Scheme) ​

Example X-PAYMENT Header Value (Before Base64 Encoding) ​

Example Request with Payment ​

Settlement Response (X-PAYMENT-RESPONSE Header) ​

Fields ​

Example X-PAYMENT-RESPONSE Header Value ​

HTTP Status Codes ​

Facilitator API ​

POST /verify ​

POST /settle ​

GET /supported ​

Error Codes ​

General Error Codes ​

Solana-Specific Error Codes ​

Next Steps ​

Protocol Reference

Payment Requirements (402 Response)

HTTP Status

Response Body

`accepts[]` Object

Example 402 Response

Payment Proof (X-PAYMENT Header)

Format

Solana Payload (Exact Scheme)

Example X-PAYMENT Header Value (Before Base64 Encoding)

Example Request with Payment

Settlement Response (X-PAYMENT-RESPONSE Header)

Fields

Example X-PAYMENT-RESPONSE Header Value

HTTP Status Codes

Facilitator API

`POST /verify`

`POST /settle`

`GET /supported`

Error Codes

General Error Codes

Solana-Specific Error Codes

Next Steps