Quickstart

By the end of this page you will have:

1. Signed up as a 0fra platform
2. Bound a wallet that receives your platform-fee cut
3. Onboarded a sub-merchant via a one-time link
4. Created a Hosted Checkout session and processed a payment

0. Prerequisites

• A wallet (MetaMask, Rabby, Coinbase Wallet) with a few drops of Base Sepolia ETH for gas
• Some Base Sepolia USDC to act as the payer (testnet faucet: Circle Sepolia)

You don't need to install anything — everything in this guide is browser + curl.

1. Sign up & onboard your platform

Open the 0fra Dashboard at localhost:5173/signup and create an account. After signup you'll be sent to the Activate page:

1. Click Connect wallet → choose your platform-treasury wallet
2. Pick a platform name (e.g. Acme Events) and your platform fee in basis points (1000 = 10%)
3. Submit. 0fra creates your account, binds the wallet, and shows you two keys:
   • sk_live_… — secret key (server-side only, shown once)
   • pk_live_… — publishable key (safe to embed in front-ends)

Save the secret key in a password manager. 0fra only stores its hash and cannot show it again.

2. Invite your first merchant

Sub-merchants self-onboard via a tokenized link — they connect their own wallet and prove ownership by signing a free message. There's no KYC for the MVP.

curl -X POST https://api.0fra.dev/v1/merchants/invitations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "vendor_2001",
    "suggested_name": "Acme Music Festival",
    "chain_id": 84532,
    "reserve_bps": 500
  }'

{
  "id": "...",
  "token": "moi_live_a1b2c3...",
  "url": "https://dash.0fra.dev/onboard/moi_live_a1b2c3...",
  "expires_at": "2026-05-02T00:00:00Z",
  "external_id": "vendor_2001"
}

Send the url to your merchant. They click, connect MetaMask, sign one EIP-191 attestation, and they're active. Their wallet is now bound to vendor_2001 on your platform.

3. Create a Hosted Checkout session

When a buyer is ready to pay, ask 0fra for a checkout session:

curl -X POST https://api.0fra.dev/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "vendor_2001",
    "order_no": "ORDER-1001",
    "chain_id": 84532,
    "token": "USDC",
    "amount": "100.00",
    "success_url": "https://acme.example/success?order=ORDER-1001",
    "cancel_url":  "https://acme.example/cart"
  }'

{
  "id": "...",
  "session_token": "cs_live_4f3...",
  "url": "https://dash.0fra.dev/checkout/cs_live_4f3...",
  "state": "open",
  "expires_at": "2026-04-25T18:30:00Z"
}

Redirect the buyer to url. They:

1. Connect their wallet on the checkout page
2. Approve USDC spend on the PaymentRouter contract (one-time per token)
3. Sign and broadcast payOrder(...) — funds flow atomically to all three parties

You'll receive an order.confirmed webhook within a minute (depending on chain confirmations).

4. Listen to webhooks

Register a webhook endpoint:

curl -X POST https://api.0fra.dev/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.example/0fra/hook",
    "subscribed_events": ["order.confirmed", "refund.completed"]
  }'

The response includes a secret (e.g. whsec_…). Each webhook delivery includes X-Webhook-Signature: v1=<hex>, computed as HMAC_SHA256(secret, "${timestamp}.${rawBody}").

See Webhooks for the full verification recipe and a list of all event types.

What's next?

• Authentication — secret keys, publishable keys, and session cookies
• Hosted Checkout — UI customization, success-URL handling, expiry
• Webhooks — signature verification, retries, idempotency
• Test mode — Base Sepolia tokens, faucets, and sandbox tips