TEZ402 // PERMIT2 UPLINK BETA

Awaiting response...

Awaiting response...

Awaiting response...

// TypeScript shapes used by this stack
type AcceptRequirement = {
  scheme: "exact";
  network: "eip155:42793";
  amount: string;
  payTo: string;
  asset: string;
  maxTimeoutSeconds: number;
  extra?: {
    assetTransferMethod?: "permit2";
    name?: string;
    decimals?: number;
  };
};

type PaymentRequired = {
  x402Version: 2;
  accepts: AcceptRequirement[];
  resource?: {
    url: string;
    mimeType?: string;
    description?: string;
  };
  error?: string;
};

type PaymentSignature = {
  x402Version: 2;
  scheme: "exact";
  network: "eip155:42793";
  accepted: AcceptRequirement;
  payload: {
    signature: string;
    permit2Authorization: {
      from: string;
      permitted: { token: string; amount: string };
      spender: string;
      nonce: string;
      deadline: string;
      witness: { to: string; validAfter: string; extra: string };
    };
  };
};

// Permit2 typed data sent to signer.signTypedData(...)
const domain = {
  name: "Permit2",
  chainId: 42793,
  verifyingContract: "0x000000000022D473030F116dDEE9F6B43aC78BA3"
};

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" },
    { name: "extra", type: "bytes" }
  ]
};

import { ethers } from "ethers";

const PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
const X402_PROXY = "0xB6FD384A0626BfeF85f3dBaf5223Dd964684B09E";
const CHAIN_ID = 42793;

const toBase64 = (obj: unknown) => {
  const bytes = new TextEncoder().encode(JSON.stringify(obj));
  return btoa(String.fromCharCode(...bytes));
};

const fromBase64 = (value: string) => {
  const bin = atob(value);
  const bytes = Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
  return JSON.parse(new TextDecoder().decode(bytes));
};

export async function payAndRetry(protectedUrl: string, signer: ethers.Signer) {
  const first = await fetch(protectedUrl);
  if (first.status !== 402) {
    return first.json();
  }

  const required = fromBase64(first.headers.get("Payment-Required") || "");
  const accepted = required.accepts[0];
  if (!accepted || accepted.extra?.assetTransferMethod !== "permit2") {
    throw new Error("No supported permit2 requirement");
  }

  const now = Math.floor(Date.now() / 1000);
  const deadline = BigInt(now + Number(accepted.maxTimeoutSeconds || 60));
  const validAfter = BigInt(now);
  const nonce = ethers.toBigInt(ethers.hexlify(ethers.randomBytes(32)));

  const permit2Authorization = {
    from: await signer.getAddress(),
    permitted: { token: accepted.asset, amount: String(accepted.amount) },
    spender: X402_PROXY,
    nonce: nonce.toString(),
    deadline: deadline.toString(),
    witness: { to: accepted.payTo, validAfter: validAfter.toString(), extra: "0x" }
  };

  const signature = await signer.signTypedData(
    { name: "Permit2", chainId: CHAIN_ID, verifyingContract: PERMIT2_ADDRESS },
    {
      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" },
        { name: "extra", type: "bytes" }
      ]
    },
    {
      permitted: { token: accepted.asset, amount: BigInt(String(accepted.amount)) },
      spender: X402_PROXY,
      nonce,
      deadline,
      witness: { to: accepted.payTo, validAfter, extra: "0x" }
    }
  );

  const paymentPayload = {
    x402Version: 2,
    scheme: "exact",
    network: "eip155:42793",
    accepted,
    payload: { signature, permit2Authorization }
  };

  const paid = await fetch(protectedUrl, {
    headers: {
      "Payment-Signature": toBase64(paymentPayload),
      "X-GAS-PAYER": "facilitator"
    }
  });

  if (!paid.ok) {
    throw new Error(`Paid request failed: ${paid.status}`);
  }
  return paid.json();
}

import base64
import json
import os
import requests
from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

FACILITATOR_URL = os.environ["FACILITATOR_URL"]
PAY_TO = os.environ["SERVER_WALLET"]
TOKEN = os.getenv("BBT_TOKEN", "0x7EfE4bdd11237610bcFca478937658bE39F8dfd6")
PROXY = os.getenv("X402_EXACT_PERMIT2_PROXY_ADDRESS", "0xB6FD384A0626BfeF85f3dBaf5223Dd964684B09E")
AMOUNT = "10000000000000000"  # 0.01 token at 18 decimals

def b64_json_encode(obj: dict) -> str:
    raw = json.dumps(obj, separators=(",", ":")).encode("utf-8")
    return base64.b64encode(raw).decode("utf-8")

def b64_json_decode(value: str) -> dict:
    return json.loads(base64.b64decode(value).decode("utf-8"))

def payment_required(resource_url: str) -> dict:
    return {
        "x402Version": 2,
        "accepts": [{
            "scheme": "exact",
            "network": "eip155:42793",
            "amount": AMOUNT,
            "payTo": PAY_TO,
            "asset": TOKEN,
            "maxTimeoutSeconds": 60,
            "extra": {"assetTransferMethod": "permit2"}
        }],
        "resource": {
            "url": resource_url,
            "mimeType": "application/json",
            "description": "Paid weather response"
        }
    }

@app.get("/api/weather")
def weather(
    payment_signature: str | None = Header(default=None, alias="Payment-Signature"),
    x_facilitator_url: str | None = Header(default=None, alias="X-Facilitator-Url")
):
    req = payment_required("https://your-store.example/api/weather")
    effective_facilitator = x_facilitator_url or FACILITATOR_URL

    if not payment_signature:
        raise HTTPException(
            status_code=402,
            detail="Payment required",
            headers={
                "Payment-Required": b64_json_encode(req),
                "X-Facilitator-Url": effective_facilitator
            }
        )

    payload = b64_json_decode(payment_signature)
    accepted = payload.get("accepted", {})
    permit2_auth = payload.get("payload", {}).get("permit2Authorization", {})

    if accepted.get("payTo", "").lower() != PAY_TO.lower():
        raise HTTPException(status_code=402, detail="Recipient mismatch")
    if accepted.get("asset", "").lower() != TOKEN.lower():
        raise HTTPException(status_code=402, detail="Asset mismatch")
    if str(accepted.get("amount")) != AMOUNT:
        raise HTTPException(status_code=402, detail="Amount mismatch")
    if permit2_auth.get("spender", "").lower() != PROXY.lower():
        raise HTTPException(status_code=402, detail="Invalid spender")

    settle_body = {
        "x402Version": 2,
        "paymentPayload": payload,
        "paymentRequirements": accepted
    }
    settle = requests.post(f"{effective_facilitator}/settle", json=settle_body, timeout=20)
    if settle.status_code >= 400:
        raise HTTPException(status_code=402, detail=f"Facilitator reject: {settle.text}")

    return {"ok": True, "settlement": settle.json()}

import json
import requests

FACILITATOR_URL = "https://exp-faci.bubbletez.com"

def require_ok(resp: requests.Response) -> dict:
    resp.raise_for_status()
    if not resp.text:
        return {}
    return resp.json()

def smoke_check():
    health = require_ok(requests.get(f"{FACILITATOR_URL}/health", timeout=10))
    supported = require_ok(requests.get(f"{FACILITATOR_URL}/supported", timeout=10))
    print("health:", json.dumps(health, indent=2))
    print("supported:", json.dumps(supported, indent=2))

    # For verify/settle testing, send:
    # {
    #   "x402Version": 2,
    #   "paymentPayload": {...decoded Payment-Signature...},
    #   "paymentRequirements": {...accepted requirement...}
    # }

if __name__ == "__main__":
    smoke_check()

1. Clone repository and configure .env values.
2. Start Docker services and verify health checks.
3. Run demo or playbook tests against your endpoints.
4. Harden production deployment with your own domains and secrets.

docker compose -f docker-compose.wallet-poc.yml up -d --build

FACILITATOR_URL=http://localhost:9090
RPC_URL=https://YOUR_ETHERLINK_RPC
CHAIN_ID=42793
SERVER_WALLET=0xYOUR_STORE_WALLET
STORE_PRIVATE_KEY=0xYOUR_STORE_PRIVATE_KEY
BBT_TOKEN=0x7EfE4bdd11237610bcFca478937658bE39F8dfd6
PERMIT2_ADDRESS=0x000000000022D473030F116dDEE9F6B43aC78BA3
X402_EXACT_PERMIT2_PROXY_ADDRESS=0xB6FD384A0626BfeF85f3dBaf5223Dd964684B09E
COMPLIANCE_PROVIDER=chainalysis
CHAINALYSIS_API_KEY=YOUR_CHAINALYSIS_KEY
PUBLIC_BASE_URL=

WALLET_ONE_PRIVATE_KEY=0x...
WALLET_TWO_PRIVATE_KEY=0x...
FACILITATOR_URL=https://exp-faci.bubbletez.com
STORE_URL=https://tez402.bubbletez.com/api/weather
# Public endpoint reference
# FACILITATOR_URL=https://exp-faci.bubbletez.com
CHAIN_ID=42793

{
  "port": 9090,
  "host": "0.0.0.0",
  "chains": {
    "eip155:42793": {
      "eip1559": true,
      "signers": ["$FACILITATOR_PRIVATE_KEY"],
      "rpc": [{ "http": "https://YOUR_ETHERLINK_RPC", "rate_limit": 100 }]
    }
  },
  "schemes": [
    { "id": "v2-eip155-exact", "chains": "eip155:42793", "enabled": true }
  ]
}

# Use published image
docker run --env-file .env -p 9090:9090 \
  -v $(pwd)/bbt_config.json:/app/bbt_config.json \
  ghcr.io/tzapac/tzapac-x402-permit2-facilitator:latest \
  --config /app/bbt_config.json

# Or build locally
docker build -t bbt-x402-facilitator:local -f bbt-x402-facilitator/Dockerfile.bbt bbt-x402-facilitator

• x402 Upstream Spec / Reference RepoProtocol reference and upstream implementation baseline.
• Repository READMEProject overview, architecture, and top-level flow.
• Quick Start GuideFastest path to run the stack and validate endpoints.
• Client Integration GuideHow to detect 402, sign Permit2, and retry with Payment-Signature.
• Server Integration GuideHow servers issue requirements and gate protected resources.
• Store Operator GuideCatalog, product setup, and settlement orchestration details.
• Facilitator Hosting GuideRun your own facilitator with allowlists and operational controls.
• Facilitator API GlossaryEndpoint contracts and payload field definitions.
• Coinbase ComparisonFeature and flow parity notes versus Coinbase implementation.
• Deployment InfoDeployment assumptions, trust boundaries, and environment notes.

Official legal terms are hosted here: BubbleTez Terms of Service.

• Who pays gas? The facilitator pays gas for settlement transactions.
• Are addresses screened? Yes, facilitator verify/settle checks enforce compliance screening before settlement.
• Do we log compliance events? Yes, this stack writes compliance audit JSONL entries for verify/settle and wallet-connect events.
• Can users reverse payment? No. Signed payments are treated as final and irreversible.

This frontend demonstrates a tez402 facilitator/store sample for Permit2-powered payment flows on Etherlink.

• You use the service in good faith and at your own risk.
• You are responsible for safeguarding your wallet, keys, and signatures.
• Verify contract addresses and facilitator endpoints before approving transactions.
• Payments and wallet signing are executed only when you explicitly initiate actions in the UI.

• The client reads wallet account and request/response data needed to request payment requirements.
• Store/facilitator operators receive wallet address, signed payment payloads, and request headers required to process settlement.
• As with typical web services, endpoint operators can see network metadata such as source IP and user agent, and may retain request/compliance logs for operations and auditing.
• This site uses Google Analytics (G-S1FE79SC2W) for anonymized usage statistics.

This is a beta implementation. Network and infrastructure behavior can change. This is not financial advice and software is provided as-is for technical evaluation.