Start here

curl -X POST https://finality.money/v1/intents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "solana",
    "token": "USDC",
    "amount": "1240.00",
    "merchant_order_id": "your-order-9527",
    "webhook_url": "https://your-site.com/webhooks/finality"
  }'

{
  "id": "9aRtUe2c-4f1b-4c3a-9e77-2b8d5f0a1c33",
  "chain": "solana",
  "token": "USDC",
  "amount": "1240.00",
  "pay_address": "7xKq...dedicated pay address...3fBw",
  "pay_url": "https://finality.money/pay/9aRtUe2c-...",
  "status": "pending",
  "expires_at": "2026-07-21T12:40:00Z"
}

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

// EVM (ERC20)
{ "chain": "base", "token": "USDC", "is_native": false,
  "to": "0x8335...",          // for ERC20, to = token contract
  "data": "0xa9059cbb...",
  "value_wei": null,
  "pay_address": "0xPay...", "amount_atomic": "49000000" }

// Solana
{ "chain": "solana", "token": "USDC", "is_native": false,
  "solana_unsigned_tx": "<base64>",
  "pay_address": "7xKq...", "amount_atomic": "49000000" }

# (1) Create an order with a sandbox key
curl -X POST https://finality.money/v1/intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "chain":"base", "token":"USDC", "amount":"49.00",
        "merchant_order_id":"test-1",
        "webhook_url":"https://your-site.com/webhooks/finality" }'

# (2) Once it reaches detected, simulate payment (a fresh pending order returns 500)
curl -X POST https://finality.money/v1/checkout/<intent_id>/simulate-pay

# (3) Your webhook endpoint receives a production-shaped event:
#   { "event":"payment.settled", "settle_tx":"SANDBOX",
#     "livemode":false, ... }

curl -X POST https://finality.money/v1/intents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "25.00",
        "merchant_order_id": "order-8802",
        "currencies": ["USDC","SOL","ETH"] }'

# Response: no pay_address yet — waiting for the customer to choose
# { "id":"...", "mode":"multi_currency", "status":"awaiting_currency",
#   "options":["solana:USDC","solana:SOL","base:USDC","base:ETH"],
#   "pay_url":"https://finality.money/pay/..." }

curl -X POST https://finality.money/v1/checkout/<intent_id>/select \
  -H "Content-Type: application/json" \
  -d '{ "currency": "solana:USDC" }'

# Response: address derived, rate locked
# { "chain":"solana", "token":"USDC", "status":"pending",
#   "pay_address":"7xKq...", "token_amount":"25.00",
#   "amount_atomic":"25000000", "expires_at":"..." }

First page
curl "https://finality.money/v1/merchant/intents?limit=50&status=settled" \
  -H "Authorization: Bearer sk_live_..."

# The cursor comes back at the end (next_cursor is null when has_more=false)
# { "intents": [...], "has_more": true,
#   "next_cursor": { "cursor_created_at": "2026-08-07T09:12:33Z",
#                    "cursor_id": "6f1c..." },
#   "stats": { "total": 1284, "settled": 1190, "settled_usd": "48210.50" } }

# Next page: echo both next_cursor fields back as-is
curl "https://finality.money/v1/merchant/intents?limit=50&status=settled\
&cursor_created_at=2026-08-07T09:12:33Z&cursor_id=6f1c..." \
  -H "Authorization: Bearer sk_live_..."

curl -X POST https://finality.money/v1/coupons \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "SAVE20", "discount_type": "percent", "discount_value": "20" }'

{
  "chain": "base",
  "token": "USDC",
  "amount": "100.00",
  "merchant_order_id": "order-8801",
  "coupon_code": "SAVE20"
}

POST https://your-site.com/webhooks/finality
X-Finality-Signature: t=1760000000,v1=3a7bd3e2360a...   // HMAC-SHA256(secret, "{t}.{raw body}"), hex
X-Finality-Event-Id:  8f2c1a9e-...           // stable id — use it to deduplicate
X-Finality-Event-Type: payment.settled

{
  "event": "payment.settled",
  "intent_id": "9aRtUe2c-4f1b-4c3a-9e77-2b8d5f0a1c33",
  "merchant_order_id": "your-order-9527",
  "chain": "solana",
  "token": "USDC",
  "amount": "1240.00",
  "livemode": true,                          // false for sandbox (sk_test_) orders
  "settle_tx": "5Kd...9Qm",                  // on-chain proof
  "payer": "3fBw...7xKq",                    // who actually paid, read from the chain
  "metadata": { "...": "whatever you sent at creation" }
}

# First find which events failed (dead=true means dead-lettered)
curl "https://finality.money/v1/merchant/webhooks?intent_id=6f1c...&limit=100" \
  -H "Authorization: Bearer sk_live_..."

# Redeliver one of them
curl -X POST https://finality.money/v1/merchant/webhooks/8f2c1a9e-.../replay \
  -H "Authorization: Bearer sk_live_..."
# → { "ok": true, "replayed": "8f2c1a9e-..." }

{
  "id": "0f4c8e2a-...",
  "name": "Pro Monthly",
  "amount": "9.99",
  "chain": "solana",
  "token": "USDC",
  "cycle_seconds": 2592000,
  "max_cycles": 0,              // 0 = renews until cancelled
  "public_checkout": false,     // you did not pass public_checkout, so this plan is invite-only
  "checkout_url": null,         // null because the plan is invite-only — this is expected
  "payout_ready": true          // false means you have not set a payout address yet: customers cannot pay
}

import express from "express";
import crypto from "crypto";

const SK = process.env.FINALITY_SECRET_KEY;        // sk_live_... (server-side only)
const WEBHOOK_SECRET = process.env.FINALITY_WEBHOOK_SECRET;
const API = "https://finality.money";

// 1. Create a plan (once at startup or from the dashboard; keep the plan_id)
async function createPlan() {
  const r = await fetch(`${API}/v1/subscriptions/plans`, {
    method: "POST",
    headers: { Authorization: `Bearer ${SK}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Pro Monthly", amount: "9.99", pricing_mode: "usd",
      chain: "solana", token: "USDC", cycle: "month",
    }),
  });
  return await r.json();             // { id, checkout_url, ... }
}

// 2. Build a subscribe link for a signed-in user (?ref= your own user ID)
function subscribeLink(plan, userId) {
  return `${plan.checkout_url}?ref=${encodeURIComponent(userId)}`;
}

// 3. Receive webhooks: verify signature (raw bytes!) + dedupe + handle by event type
const app = express();

// Header looks like t=1735689600,v1=abc123… — split on the comma first, do not compare the whole string.
// The signed message is "timestamp + a dot + the raw body" — the timestamp is inside the HMAC too.
function verifySignature(rawBody, header) {
  if (typeof header !== "string") return false;
  let t = null, v1 = null;
  for (const part of header.split(",")) {
    const [k, val] = part.trim().split("=");
    if (k === "t") t = Number(val);
    else if (k === "v1") v1 = val;
  }
  if (!Number.isFinite(t) || !v1) return false;
  // Reject anything older/newer than 5 minutes. This is what stops replays.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;

  const signed = Buffer.concat([Buffer.from(`${t}.`, "utf8"), rawBody]);
  const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(signed).digest("hex");
  // * Compare lengths first: timingSafeEqual THROWS RangeError on mismatch (not false),
  //   a short signature header would otherwise 500 this endpoint.
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhooks/finality", express.raw({ type: "*/*" }), (req, res) => {
  if (!verifySignature(req.body, req.headers["x-finality-signature"]))
    return res.sendStatus(400);

  const evt = JSON.parse(req.body);  // parse only after the signature checks out
  const userId = evt.client_reference_id;           // the user ID you passed via ?ref=
  const eventId = req.headers["x-finality-event-id"];
  if (alreadyHandled(eventId)) return res.sendStatus(200);  // idempotent — prevents double provisioning

  switch (evt.event) {
    case "subscription.active":  activateUser(userId, evt.subscription_id); break;
    case "subscription.charged": extendUser(userId, evt.next_charge_at);    break;
    case "subscription.expired": deactivateUser(userId);                    break;
    case "subscription.completed": deactivateUser(userId);                  break;  // paid in full — not a failure
  }
  markHandled(eventId);
  res.sendStatus(200);
});

app.listen(3000);

https://finality.money/subscribe/0f4c8e2a-...?ref=user_8837

POST https://your-site.com/webhooks/finality
X-Finality-Signature: t=1760000000,v1=3a7bd3e2360a...
X-Finality-Event-Type: subscription.active
X-Finality-Event-Id: evt_5f8c1a2b-...

{
  "event": "subscription.active",
  "subscription_id": "7b1e9f04-...",
  "plan_id": "0f4c8e2a-...",
  "livemode": true,
  "chain": "solana",
  "token": "USDC",
  "vault": "9xQ...v1k",
  "owner_address": "3fBw...7xKq",
  "client_reference_id": "user_8837",
  "metadata": { "plan_tier": "pro" },
  "amount": "9.99",
  "subscribe_tx": "5Kd...9Qm",
  "next_charge_at": "2026-08-30T12:00:00Z"
}

{
  "id": "3d9f...",
  "checkout_url": "https://finality.money/subscribe/0f4c8e2a-...?session=3d9f...",
  "status": "open",
  "expires_at": "2026-08-05T00:00:00Z"
}

// Only two things below need changing.
const FINALITY_KEY = "sk_live_...";   // ← 1. CHANGE THIS: Dashboard → Developers → API keys
const PLAN_ID      = "0f4c8e2a-...";  // ← 2. CHANGE THIS: Dashboard → Subscriptions → your plan

// Your site: user clicks "Subscribe" → you create their personal link.
app.post("/subscribe", async (req, res) => {
  const r = await fetch("https://finality.money/v1/subscriptions/sessions", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + FINALITY_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      plan_id: PLAN_ID,
      client_reference_id: req.user.id,   // ← YOUR user id. This comes back to you.
    }),
  });
  const session = await r.json();
  res.redirect(session.checkout_url);     // send them to checkout
});

// Your site: we call this when they pay, and on every renewal.
app.post("/webhooks/finality", async (req, res) => {
  // Always verify the signature first (see the Webhooks section).
  if (!verifyFinalitySignature(req)) return res.sendStatus(400);

  const { event, client_reference_id, subscription_id } = req.body;

  if (event === "subscription.active" || event === "subscription.charged") {
    // client_reference_id is exactly the req.user.id you sent above.
    await db.users.update(client_reference_id, {
      subscribed: true,
      finality_subscription_id: subscription_id,
    });
  }

  // "completed" = fixed-term plan paid in full. Same action (access ends),
  // but it is NOT a failure — never dun or win-back these customers.
  if (event === "subscription.canceled" || event === "subscription.expired"
      || event === "subscription.completed") {
    await db.users.update(client_reference_id, { subscribed: false });
  }

  res.sendStatus(200); // respond 200 quickly; we retry on failure
});

{
  "event": "subscription.active",
  "subscription_id": "9c1e...",

  // ✅ TRUSTED — set by you, server-side, when you created the session.
  //    The customer cannot influence this. Safe to activate an account on.
  "client_reference_id": "user_8837",

  // ⚠️ NOT TRUSTED — taken from ?ref= in the URL the customer opened.
  //    They can edit it to anything, including someone else's ID.
  //    Use it as a hint for reconciliation. NEVER to decide who gets access.
  "untrusted_ref": null
}

{
  "chain": "base",
  "direction": "upgrade",
  "new_vault": "0xNewVault...",
  "new_plan_id": "0f4c8e2a-...",
  "new_nonce": 2,
  "credit_atomic": "18300000",
  "first_amount_atomic": "80700000",
  "promo_amount_atomic": "80700000",
  "promo_cycles": 1,
  "promo_transition_atomic": "0",
  "to": "0xGateway...",
  "data": "0x...",
  "value_wei": null
}

<!-- Customers manage everything themselves — no integration needed -->
<a href="https://finality.money/account">Manage subscription</a>

<!-- Opens straight on this subscription after sign-in -->
<a href="https://finality.money/account?sub=7b1e9f04-...">Manage subscription</a>

// 1) Store the subscription id when the webhook arrives
app.post("/webhooks/finality", express.json(), (req, res) => {
  const evt = req.body;
  const userId = evt.client_reference_id;   // the user id you passed in when they subscribed

  switch (evt.event) {
    case "subscription.active":
    case "subscription.migrated":            // plan switched: the id changed, overwrite it
      db.users.update(userId, { finalitySubId: evt.subscription_id });
      break;
  }
  res.sendStatus(200);
});

// 2) Render the manage link on your account page
function manageUrl(user) {
  const id = user.finalitySubId;
  return id
    ? `https://finality.money/account?sub=${id}`
    : "https://finality.money/account";   // no id stored: the plain link still works
}

Sign in to Finality

Wallet: <WALLET_ADDRESS>
Nonce: <32_HEX_RANDOM>
Issued At: <ISO8601_UTC_NOW>

This request will not trigger a transaction or cost any gas.

curl -X POST https://finality.money/v1/account/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "<WALLET_ADDRESS>",
    "message": "<SIGNED_MESSAGE_ABOVE>",
    "signature": "<BASE58_OR_HEX_SIGNATURE>"
  }'
# -> returns owner plus a subscriptions array

const ws = new WebSocket(
  "wss://finality.money/v1/ws?intent_id=" + intentId
);

ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "error") { console.error(m.error); return; }

  // this arrival (not a running total)
  console.log(m.chain, m.token, m.amount_atomic, m.sender, m.tx_hash);

  // * to know whether it's fully paid, re-read the checkout endpoint
  fetch(`/v1/checkout/${intentId}`)
    .then(r => r.json())
    .then(v => { if (!v.is_partial && v.remaining_atomic === "0") fulfill(); });
};

{ "type": "subscription",
  "subscription_id": "3d9f...",
  "status": "active",          // active or failed
  "subscribe_tx": "0xabc..." }

{ "kind": "payment_settled",   // payment_settled / subscription_created / charged / canceled / withdrawn / vault_topup
  "chain": "base",
  "subject": "0xPayAddr...",   // subscription events = vault address; payment events = pay address
  "actor": "0xPayer...",
  "amount_atomic": 49000000,   // * a number here (the REST version returns a string)
  "token": "USDC",
  "tx_hash": "0xabc...",
  "slot": 28374611 }

import crypto from "crypto";

// Header format: "t=<unix seconds>,v1=<hex hmac>"
// The signed message is `${t}.${rawBody}` — the timestamp is INSIDE the HMAC,
// so it can't be moved forward without the secret.
const TOLERANCE_SECONDS = 300; // 5 minutes, same default as Stripe

// Constant-time compare that never throws.
// timingSafeEqual requires equal-length buffers — it throws RangeError otherwise,
// and Buffer.from(undefined) throws TypeError when the header is missing.
// Both are trivially triggerable by an attacker, so check length first.
function verify(rawBody, signature, secret) {
  if (typeof signature !== "string") return false;

  // 1) Parse "t=...,v1=..." (ignore unknown vN= parts so future versions don't break this)
  let t = null, v1 = null;
  for (const part of signature.split(",")) {
    const [k, val] = part.trim().split("=");
    if (k === "t") t = Number(val);
    else if (k === "v1") v1 = val;
  }
  if (!Number.isFinite(t) || !v1) return false;

  // 2) Reject anything outside the tolerance window — THIS is what stops replays.
  //    Without it a captured request stays valid forever.
  //    Math.abs also rejects timestamps from the future.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > TOLERANCE_SECONDS) return false;

  // 3) Verify the HMAC over "${t}.${rawBody}"
  const signedPayload = Buffer.concat([Buffer.from(`${t}.`, "utf8"), rawBody]);
  const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(v1, "utf8");
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

app.post("/webhooks/finality", express.raw({ type: "*/*" }), (req, res) => {
  // req.body is a raw Buffer here — never JSON.parse before verifying.
  if (!verify(req.body, req.headers["x-finality-signature"], process.env.FINALITY_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }

  // Deduplicate: the same event can be delivered more than once.
  const eventId = req.headers["x-finality-event-id"];
  if (await alreadyProcessed(eventId)) return res.sendStatus(200);
  await markProcessed(eventId);

  const evt = JSON.parse(req.body);
  if (evt.event === "payment.settled") {
    await fulfillOrder(evt.merchant_order_id);   // funds are in your wallet — ship it
  }
  res.sendStatus(200);
});

import hmac, hashlib, time

TOLERANCE_SECONDS = 300  # 5 minutes, same default as Stripe

@app.post("/webhooks/finality")
def finality_webhook():
    # Header format: "t=<unix seconds>,v1=<hex hmac>"; signed message is "{t}.{raw_body}"
    header = request.headers.get("X-Finality-Signature", "")
    parts = dict(
        p.strip().split("=", 1) for p in header.split(",") if "=" in p
    )
    try:
        ts = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        abort(401)

    # Reject anything outside the tolerance window — this is what stops replays.
    # abs() also rejects timestamps from the future.
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        abort(401)

    signed_payload = f"{ts}.".encode() + request.data  # raw bytes, never re-serialized
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), signed_payload, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)

    evt = request.get_json()
    if evt["event"] == "payment.settled":
        fulfill_order(evt["merchant_order_id"])
    return "", 200

<?php
// Header format: "t=<unix seconds>,v1=<hex hmac>"; signed message is "{t}.{raw_body}"
const TOLERANCE_SECONDS = 300; // 5 minutes, same default as Stripe

function finality_verify(string $rawBody, ?string $header, string $secret): bool {
    if ($header === null) return false;

    $t = null; $v1 = null;
    foreach (explode(',', $header) as $part) {
        $kv = explode('=', trim($part), 2);
        if (count($kv) !== 2) continue;
        if ($kv[0] === 't') $t = $kv[1];
        elseif ($kv[0] === 'v1') $v1 = $kv[1];
    }
    if ($t === null || $v1 === null || !ctype_digit($t)) return false;

    // Reject anything outside the tolerance window — this is what stops replays.
    if (abs(time() - (int)$t) > TOLERANCE_SECONDS) return false;

    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $v1); // constant-time
}

// php://input is the raw body — never json_encode(json_decode(...)) before hashing.
$rawBody = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_FINALITY_SIGNATURE'] ?? null;
if (!finality_verify($rawBody, $header, getenv('FINALITY_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}

$evt = json_decode($rawBody, true);
if ($evt['event'] === 'payment.settled') {
    fulfill_order($evt['merchant_order_id']); // funds are in your wallet — ship it
}
http_response_code(200);

# Native SOL (no spl-token parameter)
solana:9xQe...Recipient?amount=1.25&label=Acme&message=Order%201234

# SPL token (USDC): amount is still a decimal, not atomic units
solana:9xQe...Recipient?amount=49.00\
&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\
&label=Acme&message=Order%201234

# Native coin (ETH/BNB): value is in atomic wei
ethereum:0xRecipient...@8453?value=1000000000000000

# ERC20 (USDC on Base, 6 decimals): 49.00 USDC = 49000000
# * The path holds the TOKEN CONTRACT; the recipient moves to the address query param
ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer\
?address=0xRecipient...&uint256=49000000

{
  "chain": "base",
  "token": "USDC",
  "amount": "1000.00",
  "merchant_order_id": "mkt-order-2001",
  "splits": [
    { "address": "0xSeller...",    "bps": 8900, "label": "seller" },
    { "address": "0xPlatform...",  "bps": 700,  "label": "platform" },
    { "address": "0xAffiliate...", "bps": 300,  "label": "affiliate" }
  ]
}

curl -X POST https://finality.money/v1/affiliates \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Influencer Jane",
    "addresses": { "solana": "7xKq...3fBw", "base": "0xJane..." },
    "external_ref": "your_affiliate_id_42"
  }'
# → { "id": "b7c1e2d4-...", "ref_code": "...", ... }

curl -X POST https://finality.money/v1/affiliates/<affiliate_id>/links \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "kind": "subscription", "plan_id": "0f4c8e2a-...", "bps": 2000 }'

# -> returns a dedicated link; hand it straight to the affiliate:
{
  "ref_code": "ABC23456",
  "bps": 2000,
  "url": "https://finality.money/subscribe/0f4c8e2a-...?aff=ABC23456"
}

curl -X POST https://finality.money/v1/merchant/overpaid/prepare \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "intent_id": "6f1c9e2a-..." }'

# The response is FLAT (transaction fields at the top level, no tx wrapper)
# EVM:    { "chain","to","data","from","is_native": false }
# Solana: { "chain","solana_unsigned_tx","from" }
# You sign and broadcast this yourself — the platform never touches the money

{
  "invoice_no": "INV-202608-000731",
  "issued_at": "2026-08-07T09:14:02Z",
  "merchant": { "name": "Acme", "email": "...", "logo_url": null, "website": null },
  "order":    { "intent_id": "6f1c...", "merchant_order_id": "order-8801",
                "created_at": "2026-08-07T09:11:40Z" },
  "payment":  { "chain": "base", "token": "USDC",
                "amount_usd": "49.00", "token_amount": "49.00",
                "settle_tx": "0xabc...",
                "payer": "0xCustomer...",
                "merchant_amount": "48.51", "protocol_fee": "0.49",
                "splits_detail": [ ... ] }
}

curl "https://finality.money/v1/merchant/analytics?period=30d" \
  -H "Authorization: Bearer sk_live_..."

# top_payers groups by (payer address, chain); returning=true means a repeat customer
# { "top_payers": [
#     { "address": "0xCustomer...", "chain": "base", "orders": 4,
#       "usd": "196.00", "returning": true,
#       "first_at": "...", "last_at": "..." } ] }

# (1) Invite (owner/admin, JWT auth)
curl -X POST https://finality.money/v1/merchant/team \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "role": "viewer" }'

# → { "member_id": "...", "role": "viewer",
#     "invite_url": "https://finality.money/team/accept?token=inv_..." }
# * The token is returned only here — no endpoint can retrieve it later

# (2) The invitee registers/signs in themselves, then accepts with the token
curl -X POST https://finality.money/v1/merchant/team/accept \
  -H "Authorization: Bearer <invitee's JWT>" \
  -d '{ "token": "inv_..." }'

auth.login              2fa.enable           2fa.disable
2fa.recovery_used       api_key.create       api_key.patch
api_key.delete          webhook.rotate_secret
config.update           notify_channels.update
payout_address.update   refund.prepare       refund.confirm
team.invite             team.set_role        team.remove

# (1) Generate the secret (not active yet)
POST /v1/merchant/2fa/enable        (no body)
# → { "secret": "JBSWY3DP...", "otpauth_uri": "otpauth://totp/Finality:..." }
#   Render otpauth_uri as a QR code for the user to scan; no ready-made QR image

# (2) Confirm with the 6-digit code from the app — only now is it active
POST /v1/merchant/2fa/confirm       { "code": "123456" }
# → { "enabled": true, "recovery_codes": [ 10 eight-character codes ] }
#   * Recovery codes are returned only once; there's no reissue endpoint

// With 2FA on, login returns a challenge instead of a session token:
{ "merchant_id": "...", "need_2fa": true, "challenge": "<valid 5 minutes>" }

// prompt for the code, then exchange it for a real JWT:
POST /v1/auth/2fa   { "challenge": "...", "code": "123456" }
// → { "merchant_id": "...", "token": "<30-day JWT>", "role": "owner" }

// Without 2FA, login returns directly:
{ "merchant_id": "...", "token": "...", "role": "owner" }

# Live prices + Solana rent constants
curl https://finality.money/v1/prices
# { "sol":73.95, "eth":1918.86, "bnb":591.70, "btc":64792.59,
#   "solana_ata_rent_sol":0.00148844, "solana_account_rent_sol":0.00065024,
#   "solana_ata_rent_lamports":1488440, "solana_account_rent_lamports":650240 }
# rent figures are read live from the network — do not hardcode them

# Check a balance (all three parameters required)
curl "https://finality.money/v1/wallet-balances\
?chain=base&address=0xCustomer...&token=USDC"

<script src="https://cdn.finality.money/widget.js"></script>
<div id="pay"></div>
<script>
  finality.mount('#pay', {
    intentId: '9aRtUe2c-...',      // the id returned when your backend created the payment (UUID)
    theme: { accent:'#YourBrandColor', radius:'14px' },  // fully customizable
    onSettled: (e) => { location.href = '/success'; }  // fires when payment settles
  });
</script>

import { FinalityCheckout } from '@finality/react';

<FinalityCheckout
  intentId="9aRtUe2c-..."
  theme={{ accent: '#YourBrandColor' }}
  onSettled={(e) => router.push('/success')}
/>

# (1) No credential -> get the quote
curl -i https://finality.money/v1/x402/<intent_id>

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi...   # the same quote, base64-encoded

{ "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "1000000",
    "asset":  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo":  "0x58b3822ac31ed6c8c8bc2199575f4857920c5ea8",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }   # * read from chain, never hardcoded
  }] }

# (2) Retry with the signature -> accepted
curl -i https://finality.money/v1/x402/<intent_id> \
  -H "PAYMENT-SIGNATURE: <base64 PaymentPayload>"

HTTP/1.1 200 OK
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLC...

{
  "mcpServers": {
    "finality": {
      "command": "npx",
      "args": ["-y", "@finality/mcp"],
      "env": { "FINALITY_API_KEY": "sk_test_..." }
    }
  }
}

{ "error": "coupon invalid: expired" }

// 429 additionally carries a machine-readable code and a hint:
{ "error": "rate_limited", "message": "Too many requests", "retry_after": 30 }