loading… schema v1.0.0

pr402/x402 facilitator for solana

v1 · x402 v2

HTTP 402 Payment Required for machines. Settled on Solana.

pr402 bridges off-chain JSON agents and on-chain Solana programs. Two rails: exact (UniversalSettle) for instant payments, sla-escrow for oracle-backed delivery with buyer escrow protection — a capability standard x402 facilitators do not offer.

§probe

Confirm the live contract of this deployment from your shell. No wallet required.

Runs against this origin (loading…). Feature flags, mint allowlists, and endpoint paths live here. 

$ curl -sS "/api/v1/facilitator/capabilities" | jq .
openapi

§go live · seller

List your API in the public directory by following the six steps below. Steps 2–4 are here; steps 5–6 continue on Add your API.

Go live in 6 steps. Do them in order.

  1. 1

    Your API returns 402 when unpaid

    Integrate x402 on your server first.

    hands-on lab (Express) · seller quickstart

    on your server
  2. 2

    Preview vault addresses optional

    Read-only — skip if you like.

    go to step 2

    optional
  3. 3

    Activate your payment vault

    Connect wallet → activate below.

    go to step 3

    not started
  4. 4

    Register your shop

    API website + sign with wallet.

    go to step 4

    not started
  5. 5

    Add your API

    URL, title, sign on the register page.

    continue to step 5

    not started
  6. 6

    We verify your 402

    Automatic after step 5 when listing publicly.

    automatic

§facilitator fees · per payment transaction

deducted from payment.amount at settlement
exact · standard
100 bps · 1.00%
JIT-provisioned sellers
exact · sovereign
90 bps · 0.90%
Self-provisioned · 10 bps off
exact · min fee
$0.01 USDC
floor on protocol fee
sla-escrow · protocol
100 bps / $0.10
max(amount × bps, floor)
sla-escrow · oracle tip
100 bps · 1.00%
pure bps · no floor · paid on verdict

Seller receives amount − protocol_fee − oracle_tip. On exact there is no oracle tip. On sla-escrow the tip is paid only on verdict (resolution_state ≠ 0); capped at 500 bps per escrow. SPL floor: $0.01 USDC; SOL floor: 200 000 lamports. See /capabilities for authoritative live values.

Seller pricing (draft guide). Protocol fee = max(bps × amount, floor). On exact, a $0.01 floor means a $0.02 call pays 50% in fees — aim for ≥ ~$0.05 USDC per call. On sla-escrow, floor is $0.10 plus oracle tip — aim for ≥ ~$10 USDC per payment; use exact for smaller tickets. Activate lowers exact from 100 bps to 90 bps; ~0.1 SOL is more than enough for the one-time on-chain setup.

Buyer value · sla-escrow. Funds stay in on-chain escrow until delivery terms are met or an oracle rules — refund and release are program-enforced. Use for high-value or slow-fulfillment payments where buyer protection matters.

Preview rehearsal. preview.ipay.sh mirrors ipay.sh — flip $BASE when you go live.

wallet >

Step 2 (preview) can use a pasted pubkey only. Steps 3–4 need your wallet signature.

2

Preview vault addresses optional

read-only · no wallet · no state change
pending

Resolve your canonical vault PDAs for every supported rail. Read-only — nothing is written.

GET /api/v1/facilitator/sellers/{wallet}/preview
3

Activate

on-chain · wallet signs · sovereign 10 bps discount
pending

Creates your SplitVault (and vault ATA for SPL rails). Idempotent per (wallet, asset) — re-running is safe. Signing with the seller wallet unlocks the 10 bps sovereign discount (90 vs 100 bps).

asset >
or custom mint >
POST /api/v1/facilitator/sellers/provision-tx · one asset per wallet.
4

Register your shop

required for directory · wallet signs · step 4 of 6
pending

Registers your shop (proves wallet control) so you can list APIs in the public directory. Complete Activate (step 3) first.

API website >

Your API’s public origin (scheme + host). Step 5 resource URLs must use the same host.

More shop details (optional)

Optional extras for the merchant directory. The facilitator only verifies wallet control.

display name >
description >
tags >
next: add your API (step 5)
Continue → Add your API (steps 5–6).

Removes the wallet from /providers. No on-chain change; existing payments still settle. Use before rotating to a new wallet.

§get started

§deployments

Keep one origin per environment across seller docs, buyer build requests, /verify, and /settle. Confirm cluster and feature flags with /health on the host you call.

env recommended also available (same service)
production · mainnet ipay.sh agent.pay402.me
preview · devnet preview.ipay.sh preview.agent.pay402.me

exact GA on Mainnet. sla-escrow available to integrators who operate or trust a production oracle_authority. Reference oracles ship in the oracles workspace.

§ecosystem · payable APIs

Advisory directory of probe-approved payable resources. Pricing and accepts[] come from the live HTTP 402 on each resourceUrl. Resolve payTo via payTo semantics (GET /sellers/{wallet}/rails/{scheme}), not from this table.

Agent flow: capabilities → resources (or resource-index.json) → rails → live 402. Register your API.

§oracles

Run an oracle. Shape the trust layer.

SLA-Escrow needs oracles with domain expertise to adjudicate delivery — API quality, uptime, content integrity, etc. Reference oracles are open source.

  • Reference oracles: fork the closest sibling in the oracles workspace (api-quality / onchain-transfer / file-delivery); each ships the chain-monitor → fetch → evaluate → settle pipeline.
  • Profiles: x402/oracles/api-quality/v1, x402/oracles/onchain-transfer/v1, x402/oracles/file-delivery/attestation/v1 — hash-bound SLA + delivery, deterministic resolution_hash.
  • Economics: verdict-neutral tipping — oracles are paid for adjudication, not for the outcome.

§api inventory (canonical: /openapi.json)

method path purpose
GET /api/v1/facilitator/health rpc · ws · db · schema · environment
GET /api/v1/facilitator/capabilities features · feePayer · endpoint index · agentManifest.payToSemantics
GET /api/v1/facilitator/supported schemes · signers · rail extras
GET /agent-payTo-semantics.json payTo rules per rail (also under capabilities.agentManifest)
POST /api/v1/facilitator/verify validate payment proof (buyer)
POST /api/v1/facilitator/settle submit or confirm settlement
POST /api/v1/facilitator/build-exact-payment-tx unsigned UniversalSettle tx (buyer)
POST /api/v1/facilitator/build-sla-escrow-payment-tx unsigned FundPayment tx (buyer)
POST /api/v1/facilitator/oracle/build-confirm unsigned ConfirmOracle (oracle)
POST /api/v1/facilitator/build-refund-tx unsigned refund TransferChecked (merchant)
GET /api/v1/facilitator/sellers/{wallet}/rails/{scheme} resolve canonical payTo for 402 (seller)
GET /api/v1/facilitator/sellers/{wallet}/preview preview PDAs & fees (seller)
POST /api/v1/facilitator/sellers/provision-tx unsigned provision tx per wallet + asset (seller)
GET /api/v1/facilitator/sellers/{wallet}/challenge HMAC challenge for signed registry
POST /api/v1/facilitator/sellers/{wallet}/register submit wallet signature (seller registry)
GET /api/v1/facilitator/vault-snapshot rpc vault balances (seller diagnostics)
POST /api/v1/facilitator/payment-required/enrich expand lite 402 into full paymentRequired