开始

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...专属收款地址...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...",          // ERC20 时 to = 代币合约
  "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" }

# ① 用沙盒密钥建单
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" }'

# ② 等订单进入 detected 后, 模拟支付 (刚建好的 pending 单会 500)
curl -X POST https://finality.money/v1/checkout/<intent_id>/simulate-pay

# ③ 你的 webhook 端点会收到与生产同格式的事件:
#   { "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"] }'

# 响应: 此时还没有 pay_address, 等顾客选币
# { "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" }'

# 响应: 地址已派生, 汇率已锁定
# { "chain":"solana", "token":"USDC", "status":"pending",
#   "pay_address":"7xKq...", "token_amount":"25.00",
#   "amount_atomic":"25000000", "expires_at":"..." }

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

# 响应尾部带游标 (has_more=false 时 next_cursor 为 null)
# { "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_cursor 两个字段原样回传
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" }
}

# 先查哪些事件失败了 (dead=true 即已进死信)
curl "https://finality.money/v1/merchant/webhooks?intent_id=6f1c...&limit=100" \
  -H "Authorization: Bearer sk_live_..."

# 重新投递某一条
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 = 一直续订到取消为止
  "public_checkout": false,     // 你没有传 public_checkout，所以这个套餐只接受邀请
  "checkout_url": null,         // 因为套餐是邀请制，所以是 null —— 这是预期结果
  "payout_ready": true          // false 表示你还没配收款地址：顾客无法付款
}

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

const SK = process.env.FINALITY_SECRET_KEY;        // sk_live_... (服务端)
const WEBHOOK_SECRET = process.env.FINALITY_WEBHOOK_SECRET;
const API = "https://finality.money";

// 1. 建订阅计划 (启动时或后台点一次即可, 拿到 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. 给某个登录用户生成订阅链接 (?ref= 你系统的用户 ID)
function subscribeLink(plan, userId) {
  return `${plan.checkout_url}?ref=${encodeURIComponent(userId)}`;
}

// 3. 接收 Webhook: 验签 (原始字节!) + 幂等 + 按事件类型开通/续费/停用
const app = express();

// 请求头形如 t=1735689600,v1=abc123… —— 必须先按逗号拆开，不能整串比对。
// 被签名的原文是「时间戳 + 英文句点 + 原始请求体」—— 时间戳也在 HMAC 里面。
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;
  // 超出 5 分钟（含来自未来的）一律拒绝。这一步才是防重放的关键。
  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");
  // ★ 必须先比长度: timingSafeEqual 遇长度不等会抛 RangeError (不是返回 false),
  //   攻击者发个短签名头就能让这个端点 500。
  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);  // 验签通过后再解析
  const userId = evt.client_reference_id;           // 你 ?ref= 传的用户 ID
  const eventId = req.headers["x-finality-event-id"];
  if (alreadyHandled(eventId)) return res.sendStatus(200);  // 幂等, 防重复开通

  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;  // 已付清，不是失败
  }
  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"
}

// 下面只有两个地方需要改。
const FINALITY_KEY = "sk_live_...";   // ← 1. 改这里：后台 → 开发者 → API 密钥
const PLAN_ID      = "0f4c8e2a-...";  // ← 2. 改这里：后台 → 订阅 → 你的套餐

// 你的网站：用户点「订阅」→ 你为他生成一条专属链接。
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,   // ← 你自己的用户 ID，会原样回传给你。
    }),
  });
  const session = await r.json();
  res.redirect(session.checkout_url);     // 把顾客送去收银台
});

// 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
}

<!-- 顾客全部自助完成，无需你开发 -->
<a href="https://finality.money/account">管理订阅</a>

<!-- 登录后直接定位到这条订阅 -->
<a href="https://finality.money/account?sub=7b1e9f04-...">管理订阅</a>

// 1) 收到 webhook 时存下订阅编号
app.post("/webhooks/finality", express.json(), (req, res) => {
  const evt = req.body;
  const userId = evt.client_reference_id;   // 办卡时你传进来的用户 ID

  switch (evt.event) {
    case "subscription.active":
    case "subscription.migrated":            // 换过套餐: 编号已变, 覆盖存新的
      db.users.update(userId, { finalitySubId: evt.subscription_id });
      break;
  }
  res.sendStatus(200);
});

// 2) 在你的账户页渲染管理链接
function manageUrl(user) {
  const id = user.finalitySubId;
  return id
    ? `https://finality.money/account?sub=${id}`
    : "https://finality.money/account";   // 没存到编号: 不带参数的链接同样可用
}

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>"
  }'
# → 返回 owner 与 subscriptions 数组

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; }

  // 本笔到账 (不是累计值)
  console.log(m.chain, m.token, m.amount_atomic, m.sender, m.tx_hash);

  // ★ 判断是否付够要另外查一次收银台端点
  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 或 failed
  "subscribe_tx": "0xabc..." }

{ "kind": "payment_settled",   // payment_settled / subscription_created / charged / canceled / withdrawn / vault_topup
  "chain": "base",
  "subject": "0xPayAddr...",   // 订阅类=vault 地址, 收款类=收款地址
  "actor": "0xPayer...",
  "amount_atomic": 49000000,   // ★ 数字 (REST 版是字符串)
  "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);

# 原生 SOL (无 spl-token 参数)
solana:9xQe...Recipient?amount=1.25&label=Acme&message=Order%201234

# SPL 代币 (USDC): amount 仍是小数, 不是原子量
solana:9xQe...Recipient?amount=49.00\
&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\
&label=Acme&message=Order%201234

# 原生币 (ETH/BNB): value = wei 原子量
ethereum:0xRecipient...@8453?value=1000000000000000

# ERC20 (USDC on Base, 6 位小数): 49.00 USDC = 49000000
# ★ 路径上是「代币合约地址」, 收款人挪到 query 的 address
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 }'

# → 返回专属链接, 直接甩给分销商去推广:
{
  "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-..." }'

# 响应是「扁平」结构 (交易字段直接在顶层, 没有 tx 包裹层)
# EVM:    { "chain","to","data","from","is_native": false }
# Solana: { "chain","solana_unsigned_tx","from" }
# 同样由你自己签名广播, 平台不碰钱

{
  "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 按 (付款地址, 链) 聚合, returning=true 表示回头客
# { "top_payers": [
#     { "address": "0xCustomer...", "chain": "base", "orders": 4,
#       "usd": "196.00", "returning": true,
#       "first_at": "...", "last_at": "..." } ] }

# ① 邀请 (owner/admin, JWT 鉴权)
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_..." }
# ★ token 只在这里返回一次, 之后任何端点都取不回来

# ② 被邀请人自己注册/登录后, 带 token 接受
curl -X POST https://finality.money/v1/merchant/team/accept \
  -H "Authorization: Bearer <被邀请人的 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

# ① 生成 secret (此时还没生效)
POST /v1/merchant/2fa/enable        (无 body)
# → { "secret": "JBSWY3DP...", "otpauth_uri": "otpauth://totp/Finality:..." }
#   把 otpauth_uri 编成二维码给用户扫; 没有现成 QR 图片

# ② 输入 App 上的 6 位码确认, 此时才真正开启
POST /v1/merchant/2fa/confirm       { "code": "123456" }
# → { "enabled": true, "recovery_codes": [ 10 个 8 位码 ] }
#   ★ 恢复码只返回这一次, 没有补发端点

// 开了 2FA 时, 登录接口不发正式 token, 改发 challenge:
{ "merchant_id": "...", "need_2fa": true, "challenge": "<5 分钟有效>" }

// 前端弹码框, 再换正式 JWT:
POST /v1/auth/2fa   { "challenge": "...", "code": "123456" }
// → { "merchant_id": "...", "token": "<30 天 JWT>", "role": "owner" }

// 未开 2FA 时, 登录直接返回:
{ "merchant_id": "...", "token": "...", "role": "owner" }

# 实时币价 + Solana rent 常量
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

# 查余额 (三个参数缺一不可)
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-...',      // 后端创建收款返回的 id (UUID)
    theme: { accent:'#你的品牌色', radius:'14px' },  // 自由定制
    onSettled: (e) => { location.href = '/success'; }  // 付款成功回调
  });
</script>

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

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

# ① 不带凭证 → 拿报价单
curl -i https://finality.money/v1/x402/<intent_id>

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi...   # 同一份报价单的 base64

{ "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "1000000",
    "asset":  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo":  "0x58b3822ac31ed6c8c8bc2199575f4857920c5ea8",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }   # ★ 链上读到的真值, 不是硬编码
  }] }

# ② 带签名重发 → 放行
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 }