Open APIs V2

Copy page

Permit2 signing guide (permit2-exact)

This page is a self-contained reference for producing valid permit2-exact payloads that B402 V2 accepts. Use this when your asset does not support EIP-3009 (e.g. USDT on BSC) — Permit2 is the only path to /papi/v2/b402/settle in that case.

The stock @x402/evm client library is EIP-3009 focused and does not ship a Permit2 signer. You construct the EIP-712 typed data yourself with viem or ethers.js, then drop the signature into paymentPayload.payload.permit2Authorization.

permit2-upto uses a different witness struct and is out of scope for this page — contact the B402 team if you need it.

How it works

1. Payer wallet approves Permit2 once on the token contract (standard ERC-20 approve(permit2, max) — one-time, per token, per wallet).
2. For each payment, the payer signs an EIP-712 PermitWitnessTransferFrom message (typed data below). The witness binds the signature to the merchant's payTo, so a settled signature can only pay that merchant.
3. You POST the signed envelope to /papi/v2/b402/verify (off-chain check) and then /papi/v2/b402/settle. B402's facilitator calls Permit2.permitWitnessTransferFrom(...) on-chain with gas sponsored.

Prerequisites

Item	Value	Notes
Permit2 contract	0x000000000022D473030F116dDEE9F6B43aC78BA3	Canonical deployment — same address on every EVM chain.
Payer's Permit2 approval	token.approve(0x000000000022D473030F116dDEE9F6B43aC78BA3, 2^256-1)	One-time per (wallet, token) pair. If the payer has used any Uniswap / Permit2-integrated dapp before, this is usually already set.
extra.signerAddress	facilitator EOA	Returned by /supported under the matching kinds[] entry. Surface it to buyers.
extra.spenderAddress	Permit2 proxy contract	Returned by /supported. This is the spender in the typed data message, not the facilitator EOA.

Note: spenderAddress changes if b402 redeploys the proxy contract. Always read it fresh from /supported rather than hard-coding.

Step 1 — Build the EIP-712 typed data

Domain

Permit2 uses a three-field EIP-712 domain. There is no version field — adding one will change the domain separator and your signatures will be rejected.

Code
{
  "name": "Permit2",
  "chainId": 56,
  "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
}

Use chainId 56 for BSC mainnet or 97 for BSC testnet. The verifyingContract is constant across all chains.

Types

Code
{
  "PermitWitnessTransferFrom": [
    { "name": "permitted", "type": "TokenPermissions" },
    { "name": "spender", "type": "address" },
    { "name": "nonce", "type": "uint256" },
    { "name": "deadline", "type": "uint256" },
    { "name": "witness", "type": "Witness" }
  ],
  "TokenPermissions": [
    { "name": "token", "type": "address" },
    { "name": "amount", "type": "uint256" }
  ],
  "Witness": [
    { "name": "to", "type": "address" },
    { "name": "validAfter", "type": "uint256" }
  ]
}

Field order is load-bearing. EIP-712 hashes struct fields in declaration order. Swapping to and validAfter (or any other pair) produces a digest that looks valid but fails the on-chain check. The Witness struct name must be exactly Witness — not B402Witness or anything else.

primaryType

Code
PermitWitnessTransferFrom

Message

Field	Source	Notes
permitted.token	paymentRequirements.asset	ERC-20 token contract address
permitted.amount	paymentRequirements.amount	Exact amount in atomic units — authorized and settled 1:1
spender	paymentRequirements.extra.spenderAddress	Permit2 proxy contract address — not the facilitator EOA and not the signer
nonce	256-bit random	Permit2 uses a bitmap; generate fresh random bytes per signature
deadline	unix seconds, now + 3600	Signature expiry
witness.to	paymentRequirements.payTo	Merchant wallet — the on-chain transfer recipient
witness.validAfter	unix seconds, now − 60	Earliest time settlement can execute. Back-dating by 60 s absorbs client/server clock skew. "0" is also valid (signature usable immediately); replay protection comes from nonce, not validAfter.

Step 2 — Sign it

TypeScript — viem (recommended)

Signing is a pure local operation — no RPC needed. privateKeyToAccount(...).signTypedData(...) is enough.

Code
import { privateKeyToAccount } from "viem/accounts";
import { randomBytes } from "crypto";

const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";

// `requirements` is the `paymentRequirements` object the merchant returned.
async function signPermit2Exact(
  requirements: {
    network: string; // CAIP-2, e.g. "eip155:56" (mainnet) or "eip155:97" (testnet)
    amount: string; // atomic units
    asset: string; // token contract
    payTo: string; // merchant
    extra: { spenderAddress: string };
  },
  privateKey: `0x${string}`,
) {
  const account = privateKeyToAccount(privateKey);

  const chainId = Number(requirements.network.split(":")[1]);
  const nowSec = Math.floor(Date.now() / 1000);
  const nonce = BigInt("0x" + Buffer.from(randomBytes(32)).toString("hex")).toString();
  const deadline = (nowSec + 3600).toString();
  const validAfter = (nowSec - 60).toString();

  const signature = await account.signTypedData({
    domain: {
      name: "Permit2",
      chainId,
      verifyingContract: PERMIT2,
    },
    types: {
      PermitWitnessTransferFrom: [
        { name: "permitted", type: "TokenPermissions" },
        { name: "spender", type: "address" },
        { name: "nonce", type: "uint256" },
        { name: "deadline", type: "uint256" },
        { name: "witness", type: "Witness" },
      ],
      TokenPermissions: [
        { name: "token", type: "address" },
        { name: "amount", type: "uint256" },
      ],
      Witness: [
        { name: "to", type: "address" },
        { name: "validAfter", type: "uint256" },
      ],
    },
    primaryType: "PermitWitnessTransferFrom",
    message: {
      permitted: {
        token: requirements.asset as `0x${string}`,
        amount: BigInt(requirements.amount),
      },
      spender: requirements.extra.spenderAddress as `0x${string}`,
      nonce: BigInt(nonce),
      deadline: BigInt(deadline),
      witness: { to: requirements.payTo as `0x${string}`, validAfter: BigInt(validAfter) },
    },
  });

  // Build the wire envelope — numeric fields become decimal strings at the boundary.
  return {
    signature,
    permit2Authorization: {
      permitted: { token: requirements.asset, amount: requirements.amount },
      from: account.address,
      spender: requirements.extra.spenderAddress,
      nonce,
      deadline,
      witness: { to: requirements.payTo, validAfter },
    },
  };
}

TypeScript — ethers.js v6

Code
import { Wallet, toBigInt, hexlify, randomBytes } from "ethers";

const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";

async function signPermit2Exact(
  requirements: {
    network: string;
    amount: string;
    asset: string;
    payTo: string;
    extra: { spenderAddress: string };
  },
  privateKey: string,
) {
  // No provider needed — EIP-712 signing is a pure local operation.
  const wallet = new Wallet(privateKey);
  const chainId = Number(requirements.network.split(":")[1]);
  const nowSec = Math.floor(Date.now() / 1000);
  const nonce = toBigInt(hexlify(randomBytes(32))).toString();
  const deadline = (nowSec + 3600).toString();
  const validAfter = (nowSec - 60).toString();

  const domain = {
    name: "Permit2",
    chainId,
    verifyingContract: PERMIT2,
  };
  const types = {
    PermitWitnessTransferFrom: [
      { name: "permitted", type: "TokenPermissions" },
      { name: "spender", type: "address" },
      { name: "nonce", type: "uint256" },
      { name: "deadline", type: "uint256" },
      { name: "witness", type: "Witness" },
    ],
    TokenPermissions: [
      { name: "token", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    Witness: [
      { name: "to", type: "address" },
      { name: "validAfter", type: "uint256" },
    ],
  };
  const message = {
    permitted: { token: requirements.asset, amount: requirements.amount },
    spender: requirements.extra.spenderAddress,
    nonce,
    deadline,
    witness: { to: requirements.payTo, validAfter },
  };

  const signature = await wallet.signTypedData(domain, types, message);

  return {
    signature,
    permit2Authorization: {
      permitted: { token: requirements.asset, amount: requirements.amount },
      from: wallet.address,
      spender: requirements.extra.spenderAddress,
      nonce,
      deadline,
      witness: { to: requirements.payTo, validAfter },
    },
  };
}

Note: ethers.js v6's signTypedData auto-derives EIP712Domain. Viem does the same. Do not add EIP712Domain to the types map manually — both libraries will reject it.

Step 3 — Build the wire envelope

Drop the signature and permit2Authorization into the V2 PaymentPayload shape. See Verify Payment — Example — Permit2 Exact for the full JSON.

Code
{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.example.com/premium/data",
      "description": "...",
      "mimeType": "application/json"
    },
    "accepted": { "...": "echoed paymentRequirements" },
    "payload": {
      "signature": "0x<65-byte hex>",
      "permit2Authorization": {
        "permitted": { "token": "0x55d398...", "amount": "5000000" },
        "from": "0x<payer>",
        "spender": "0x<extra.spenderAddress>",
        "nonce": "<decimal string>",
        "deadline": "<unix seconds, decimal string>",
        "witness": {
          "to": "0x<merchant payTo>",
          "validAfter": "<unix seconds, decimal string>"
        }
      }
    }
  },
  "paymentRequirements": { "...": "same object as paymentPayload.accepted" }
}

All numeric fields (nonce, deadline, validAfter, amount) are decimal strings on the wire, but uint256 inside the EIP-712 typed data. Both the EIP-712 signing libraries above accept the bigint/string types natively — just ensure the string you put on the wire matches the value that was signed.

Common pitfalls

1. Adding version to the domain. Permit2's domain has exactly {name, chainId, verifyingContract}. If you spread a { version: '1' } in, the domain separator changes and /verify returns invalid_exact_evm_payload_signature.
2. spender = proxy, not signer. extra.spenderAddress (the Permit2 proxy contract) goes in spender. The facilitator EOA (extra.signerAddress) does not appear in the Permit2 exact typed data — it's only used by permit2-upto.
3. Witness field order. Must be (to, validAfter) — in that order — for both the struct name Witness and its field list. Swapping fields or renaming the struct breaks the typehash.
4. Wire format vs typed data. nonce, deadline, validAfter, amount sign as uint256 but travel as decimal strings on the JSON wire. Library serialization usually handles this; if you see invalid_payload, check that the string representations match.
5. Forgetting the Permit2 approval — or granting a finite one. If the payer's wallet has never approved Permit2 on this token, the on-chain permitWitnessTransferFrom reverts with TRANSFER_FROM_FAILED at /settle (verify does not check this). Granting a finite approval (e.g. exactly the first payment amount) works once, but the allowance is consumed on each transfer and later payments will revert the same way. Recommend token.approve(permit2, 2^256-1) once per (wallet, token).
6. Signature length / prefix. The signature is a 0x-prefixed 65-byte hex string (r || s || v). Both viem and ethers.js return this shape natively; don't trim or reformat.
7. Clock skew. If validAfter is later than the facilitator's block.timestamp at settle time, the proxy reverts. Back-dating by 60 s is conservative; shorter backdates are fine if your clocks are NTP-synced.

End-to-end walkthrough

1. Fetch configurations: POST /papi/v2/b402/supported (with {} body, RSA-signed). Find the kinds[] entry with asset == <your USDT address> and assetTransferMethod == "permit2-exact". Read extra.spenderAddress and extra.signerAddress.
2. Merchant constructs paymentRequirements using the chosen kind; surface extra.spenderAddress and extra.signerAddress to the buyer (HTTP 402 response body).
3. Buyer signs the EIP-712 payload as shown above, producing signature and permit2Authorization.
4. Buyer POSTs envelope to POST /papi/v2/b402/verify. Expect isValid: true.
5. Merchant POSTs the same envelope to POST /papi/v2/b402/settle. Expect success: true with an on-chain transaction hash.

Troubleshooting

Symptom	Likely cause
invalid_exact_evm_payload_signature	Domain / types / field-order mismatch, or signing with a key that doesn't own the from address
invalid_exact_evm_payload_authorization_valid_after	validAfter is in the future; reduce the backdate or wait
invalid_exact_evm_payload_authorization_valid_before	deadline is in the past; sign a fresh payload
invalid_exact_evm_payload_recipient_mismatch	witness.to doesn't match paymentRequirements.payTo
invalid_exact_evm_payload_authorization_value_mismatch	permitted.amount < paymentRequirements.amount
invalid_network	chainId in domain doesn't match the CAIP-2 network in paymentRequirements.network
/settle returns invalid_transaction_state with TRANSFER_FROM_FAILED on-chain	Payer hasn't approved Permit2 on the token, or has insufficient balance
invalid_payload	Wire field types off — check decimal-string encoding of numeric fields

Still stuck? Send us the failing paymentPayload JSON and the response — we can match the digest against what B402 recovered and pinpoint the mismatch.