Skip to main content

​
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. 🔗 GitHub: Singularity-SDK 🔑 JWKS Endpoint: api.x402layer.cc/.well-known/jwks.json 📦 All packages: see the platform-wide SDKs & Packages catalog.

​
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.
  1. Client hits your API — Without a valid receipt token
  2. SDK middleware returns 402 — With x402 payment instructions
  3. Client pays via x402 — Receives a signed receipt JWT
  4. Client retries with receipt — Token in header
  5. SDK verifies receipt — Cryptographic signature check against JWKS public keys → access granted

​
Installation

​
Node.js

npm install x402sgl

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

​
Python

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

from x402layer_middleware import X402ReceiptVerifier, require_x402_receipt
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.
PropertyValue
AlgorithmRS256
JWKS URLhttps://api.x402layer.cc/.well-known/jwks.json
Issuerhttps://api.x402layer.cc
Audiencex402layer:receipt

​
Receipt Claims

ClaimTypeDescription
eventstring"payment.succeeded"
sourcestring"endpoint" | "product"
source_idstringUUID of the resource
source_slugstringSlug of the resource
amountstringPayment amount (e.g. "1.00")
currencystringAsset symbol ("USDC" or "USDm")
tx_hashstringOn-chain transaction hash
payer_walletstringBuyer wallet address
networkstring"base" | "solana" | "megaeth"
statusstringSettlement status
iatnumberIssued-at timestamp (Unix)
expnumberExpiration timestamp (Unix)
jtistringUnique receipt ID

​
Node.js Quick Start

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

// 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' });
  }
);
Manual verification: 
const { verifyX402ReceiptToken } = require('x402sgl');

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

​
Python / FastAPI Quick Start

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: 
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 in production — 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).