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

ā€‹
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 (e.g. "USDC")
tx_hashstringOn-chain transaction hash
payer_walletstringBuyer wallet address
networkstring"base" | "solana"
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).