SDK & Receipts

Every successful payment through x402 Studio returns a signed receipt token (JWT). The x402layer SDK lets you verify these receipts server-side to gate premium content, confirm purchases, or audit payments.

View on GitHub 🔑 JWKS Endpoint

How It Works

When a payment is processed through x402, the worker signs a receipt JWT with a private key. The SDK verifies that signature using the corresponding public key from the JWKS endpoint — proving the receipt is genuine and untampered.

Client hits your API

Without a valid receipt token

SDK middleware returns 402

With x402 payment instructions

Client pays via x402

Receives a signed receipt JWT

Client retries with receipt

Token in header

SDK verifies receipt

Cryptographic signature check against JWKS public keys → access granted

Installation

Node.js

npm install x402sgl

Python

pip install git+https://github.com/ivaavimusic/Singularity-SDK.git#subdirectory=python

Dependencies (PyJWT, cryptography) are installed automatically. For FastAPI support: pip install x402layer-sdk[fastapi]

Receipt Token Contract

Receipt tokens are standard JWTs signed with RS256. Public keys are served from the JWKS endpoint for verification.

Algorithm

RS256

JWKS URL

https://api.x402layer.cc/.well-known/jwks.json

Issuer

https://api.x402layer.cc

Audience

x402layer:receipt

Receipt Claims

Claim	Type	Description
event	string	"payment.succeeded"
source	string	"endpoint" \| "product"
source_id	string	UUID of the resource
source_slug	string	Slug of the resource
amount	string	Payment amount (e.g. "1.00")
currency	string	Asset symbol (e.g. "USDC")
tx_hash	string	On-chain transaction hash
payer_wallet	string	Buyer wallet address
network	string	"base" \| "solana"
status	string	Settlement status
iat	number	Issued-at timestamp (Unix)
exp	number	Expiration timestamp (Unix)
jti	string	Unique receipt ID

Node.js Quick Start

The Node SDK works with Express (or any framework). It fetches JWKS keys automatically and caches them.

Express — Protect a Routejavascript

const { createX402ReceiptMiddleware } = require('x402sgl');

// 2. Protect any route
app.get(
  '/premium-data',
  createX402ReceiptMiddleware({
    requiredSourceSlug: 'my-api-endpoint'  // prevents token replay
  }),
  (req, res) => {
    // req.x402Receipt contains the verified claims
    console.log('Paid by:', req.x402Receipt.payer_wallet);
    console.log('Amount:', req.x402Receipt.amount, req.x402Receipt.currency);
    res.json({ data: 'premium content here' });
  }
);

Or verify a token manually:

Manual Verificationjavascript

const { verifyX402ReceiptToken } = require('x402sgl');

const claims = await verifyX402ReceiptToken(token);
// claims.source_slug, claims.amount, claims.tx_hash, etc.

Python / FastAPI Quick Start

The Python SDK integrates as a FastAPI dependency.

Install Dependenciesbash

pip install PyJWT cryptography requests

FastAPI — Protect a Routepython

from x402layer_middleware import X402ReceiptVerifier, require_x402_receipt

verifier = X402ReceiptVerifier()

@app.get("/premium")
async def premium_endpoint(
    receipt=require_x402_receipt(verifier, required_source_slug="my-endpoint")
):
    print(f"Paid by: {receipt['payer_wallet']}")
    return {"ok": True, "amount": receipt["amount"]}

Where the Token Comes From

After a successful payment, the x402 worker includes the receipt token in the response header:

Response Headerhttp

X-X402-Receipt-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlY2VpcHQtdjEifQ...

Your client should extract this token and include it in subsequent requests to your backend, either as an Authorization: Bearer header or the X-X402-Receipt-Token header.

Security Notes

🛡️

Always set requiredSourceSlug

This prevents a receipt for endpoint A being replayed against endpoint B.

🔄

Key rotation

Publish a new JWKS key with a new kid, then update the worker private key. Old tokens remain verifiable until they expire.

⏳

Expiration

Receipt tokens have a limited lifetime. Always check the exp claim (the SDK does this automatically).

📡 Webhooks →🔗 Creating Endpoints →