x402: HTTP 402 reborn — internet-native payments, on Solana

Client → Server   GET /paid-endpoint
Server → Client   HTTP/1.1 402 Payment Required
                  X-Payment-Required: {
                    "scheme":  "exact",
                    "network": "solana-mainnet",
                    "asset":   "USDC",
                    "amount":  "0.01",
                    "payTo":   "<merchant-solana-address>",
                    "resource":"/paid-endpoint",
                    "nonce":   "<server-issued>",
                    "expires": "<unix-ts>"
                  }

Client signs + submits a payment tx to Solana
Client → Server   GET /paid-endpoint
                  X-Payment: {
                    "scheme":  "exact",
                    "txid":    "<solana-signature>",
                    "nonce":   "<from-above>"
                  }

Server verifies on Solana that the tx matches the requirement
Server → Client   HTTP/1.1 200 OK
                  <the actual content>

import { Connection, Transaction, PublicKey } from "@solana/web3.js"
import {
  getOrCreateAssociatedTokenAccount, createTransferCheckedInstruction,
} from "@solana/spl-token"
import { createMemoInstruction } from "@solana/spl-memo"

const conn = new Connection("https://api.mainnet-beta.solana.com")
const USDC = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")

// From the X-Payment-Required header:
const { payTo, amount, nonce } = paymentRequired

const fromAta = await getOrCreateAssociatedTokenAccount(
  conn, payer, USDC, payer.publicKey,
)
const toAta = await getOrCreateAssociatedTokenAccount(
  conn, payer, USDC, new PublicKey(payTo),
)

const tx = new Transaction()
  .add(createTransferCheckedInstruction(
    fromAta.address, USDC, toAta.address, payer.publicKey,
    Math.floor(parseFloat(amount) * 1_000_000),  // USDC has 6 decimals
    6, [],
  ))
  .add(createMemoInstruction(nonce, [payer.publicKey]))

const sig = await conn.sendTransaction(tx, [payer])

// Now retry the request:
const resp = await fetch("/paid-endpoint", {
  headers: {
    "X-Payment": JSON.stringify({ scheme: "exact", txid: sig, nonce }),
  },
})

import { Connection, PublicKey, ParsedAccountData } from "@solana/web3.js"

async function verifyPayment(
  conn: Connection,
  xPayment: { txid: string; nonce: string },
  requirement: { payTo: string; amount: string; nonce: string },
): Promise<boolean> {
  if (xPayment.nonce !== requirement.nonce) return false

  // Fetch the parsed tx
  const tx = await conn.getParsedTransaction(xPayment.txid, "confirmed")
  if (!tx || tx.meta?.err) return false

  // Find the SPL transfer to our merchant address
  const instructions = tx.transaction.message.instructions
  const transfer = instructions.find((ix) => {
    if (!("parsed" in ix)) return false
    return ix.program === "spl-token" && ix.parsed.type === "transferChecked"
  }) as any
  if (!transfer) return false

  const info = transfer.parsed.info
  if (info.destination !== merchantUsdcAta) return false  // pre-computed
  const expected = Math.floor(parseFloat(requirement.amount) * 1_000_000)
  if (parseInt(info.tokenAmount.amount) !== expected) return false

  // Verify the memo contains the nonce
  const memo = instructions.find((ix) => "parsed" in ix && ix.program === "spl-memo") as any
  if (!memo || memo.parsed !== requirement.nonce) return false

  return true
}