FAQ
Authentication
Q: How does challenge-response work?
Server generates unique message, user signs it, server verifies signature and checks license. Reusable until expiration.
Q: How long is a challenge valid?
Default 5 minutes, configurable via ttl parameter. Can be set up to hours for longer sessions.
Q: Do I need to sign for every request?
No. One challenge signature works for multiple requests until expiration.
Q: What if the challenge expires?
Request a new challenge. The client should handle this automatically.
Licenses
Q: What is a license?
A cryptographic receipt that grants access to content. Contains SKU, usage type, and optional expiration.
Q: What usage types are supported?
single_use- One-time access, marked as used after first verificationunlimited- Unlimited access until expiration (if set)
Q: How do I set an expiration?
Include expirationDate (Unix timestamp) in x402Meta when settling payment.
Q: Can licenses be revoked?
Not currently. Revocation support planned for future release.
Integration
Q: Do I need to change my x402 endpoints?
No. Keep /verify and /settle paths. Point them to the facilitator URL.
Q: What is X-PAYMENT-META?
Optional header for x402 compatibility. Contains base64url-encoded payment metadata.
Q: Can I use session tokens instead of challenges?
Yes. After initial challenge verification, server can issue JWT session tokens for faster subsequent requests.
Q: Is on-chain storage required?
No. Receipts are signed JSON. On-chain inscription is optional for permanence.
Technical
Q: What signature algorithm is used?
Ed25519 (Solana standard). Signatures verified using tweetnacl.
Q: What encoding for signatures?
Base58 (Solana standard). Base64 and base64url also supported.
Q: How are receipts stored?
Configurable storage backend. Supports PostgreSQL, in-memory, or custom adapters.
Q: Can I run my own facilitator?
Yes. The code is open source. Configure with your own RPC endpoints and storage.
Troubleshooting
Q: Getting "challenge_not_found" error?
Challenge expired or doesn't exist. Request a new challenge.
Q: Getting "no_license" error?
Wallet doesn't own a valid license for the SKU. User needs to purchase first.
Q: Getting "invalid_signature" error?
Signature verification failed. Ensure correct wallet signed the exact challenge message.
Q: Payment not confirming?
Check transaction on blockchain explorer. May need to wait for confirmation (usually 1-2 seconds on Solana).