API Reference

Base URL: https://facilitator.pop402.com

Authentication Endpoints

POST /challenge

Generate authentication challenge.

Request:

• walletAddress (string, required) - Base58 Solana address
• ttl (number, optional) - Seconds until expiration (default: 300)

Response:

• challenge.id - Unique challenge identifier
• challenge.message - Message to sign
• challenge.expiresAt - Unix timestamp
• challenge.expiresIn - Seconds until expiration

POST /verify

Verify payment or challenge.

Request:

• paymentPayload.x402Meta (object) - Payment metadata
  • challengeId (string) - For challenge auth
  • signature (string) - Base58 signature
  • walletAddress (string) - Base58 address
  • sku (string) - Product identifier
• paymentRequirements (object)
  • network (string) - "solana" or "solana-devnet"

Response:

• isValid (boolean) - Access granted
• payer (string) - Wallet address
• invalidReason (string, optional) - Error code

POST /settle

Process payment and generate receipt.

Request:

• Same structure as /verify
• Additional metadata for receipt generation

Response:

• success (boolean)
• receiptId (string) - Receipt identifier
• transaction (string) - Transaction signature
• network (string)

Metadata Fields

x402Meta Object

Challenge Auth:

• challengeId - Challenge identifier
• signature - Wallet signature
• walletAddress - Payer address
• sku - Product SKU

License Info:

• usageType - "single_use" | "unlimited"
• expirationDate - Unix timestamp (optional)

Branding:

• buyerEmail - Buyer email for receipt
• sellerEmail - Seller notification email
• logoUrl - Logo URL for receipt
• primaryColor - Brand color hex
• secondaryColor - Accent color hex

Error Codes

Challenge Errors

• challenge_not_found - Challenge doesn't exist
• challenge_expired - TTL passed
• wallet_mismatch - Wrong wallet
• invalid_signature - Bad signature

License Errors

• no_license - No valid license
• license_expired - License past expiration
• usage_exhausted - Single-use license already used

Payment Errors

• invalid_transaction - Transaction validation failed
• transaction_failed - Blockchain error
• insufficient_payment - Amount too low

Rate Limits

• 100 requests per minute per IP
• 1000 requests per hour per wallet

Networks

Supported networks:

• solana - Mainnet
• solana-devnet - Devnet for testing