ネイティブ REST API

ネイティブ API は blockwallets 独自の REST インターフェースです。米セント建ての請求、注文ごとの冪等な ref、全ネットワークに対応する固定の入金アカウント、HMAC-SHA256 で署名された Webhook を備えています。Cryptomus 互換 API と同じホスト型決済ページに同じ請求が作られ、手数料と残高も同じです。

キーは管理画面の「開発者 › 連携とキー」で自分で発行します:Live キーと Test キー、およびそれぞれの Webhook 署名シークレット。どれも表示は一度だけで、一覧にはプレフィックスしか表示されません。アカウントで二段階認証を有効にしている場合、Live キーの発行やローテーションにはコードの入力が必要です。加盟店アカウントがまだない場合は利用を申し込んでください。すでに Cryptomus を使っている場合はCryptomus 互換 APIをご覧ください(選び方)。

キーとリクエスト

ベース URL は https://blockwallets.io です。リクエストとレスポンスは JSON で、すべてのリクエストに次を付けます。

• Authorization: Bearer bw_live_… または Bearer bw_test_…:プレフィックスでモードが決まります。Test キーには Test の請求だけが見え、テストネットで動作します
• POST リクエストには Content-Type: application/json
• キーはサーバー上だけで保管し、ウェブページやアプリには絶対に入れないでください。当社にはそのハッシュだけを保存します

エラーは HTTP ステータスと {"error": {"code": "…", "message": "…"}} で返ります:400 invalid_request(フィールドの不足または形式不正)、401 unauthorized(キーがない、不明、または無効)、404 not_found、409 conflict(請求の現在の状態と矛盾するリクエスト)、422 currency_unsupported。

エンドポイント

請求または入金アカウントの照会に ?probe=1 を付けると、その場でチェーンも確認します(10 秒に1回まで)。付けない場合は、毎分確認しているスキャナーの最新の状態が返ります。

請求を作成 POST /v1/invoices

お客様が会計に進んだら POST /v1/invoices を呼び出し、レスポンスの pay_url へリダイレクトします。

curl -X POST https://blockwallets.io/v1/invoices \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"order_1042","amount":4200,"title":"Order #1042",
       "return_url":"https://shop.example/cart","success_url":"https://shop.example/thanks?order=1042",
       "meta":{"user_id":42}}'

すべての URL はサイトのドメイン上である必要があります(管理画面 →「開発者 › 連携とキー」)。レスポンスは下記の請求オブジェクトです。network、address、pay_amount は、ネットワークが選ばれたあとに設定されます。

請求オブジェクト

id は inv_ で始まります。amount は米セント、pay_amount と paid_amount は選ばれたネットワーク上のコイン数量(小数の文字列)です。

{
  "id": "inv_01J8…",
  "ref": "order_1042",
  "mode": "live",
  "status": "pending",
  "amount": 4200,
  "currency": "USD",
  "title": "Order #1042",
  "meta": { "user_id": 42 },
  "network": null,
  "address": null,
  "pay_amount": null,
  "paid_amount": null,
  "payments": [],
  "pay_url": "https://blockwallets.io/pay/inv_01J8…",
  "return_url": "https://shop.example/cart",
  "success_url": "https://shop.example/thanks?order=1042",
  "created_at": "2026-11-03T08:00:00.000Z",
  "expires_at": "2026-11-03T09:00:00.000Z",
  "paid_at": null,
  "closed_at": null
}

その他のフィールド:pay_url(ホスト型決済ページ)、payments(各送金の txid、amount、confirmations、confirmed)、expires_at、paid_at、closed_at。BTC、LTC、DOGE、BCH、ネイティブ通貨には rate(コイン1枚あたりの米ドル、30 分間固定)、rate_locked_until、paid_cents(届いた分の米セント換算)も付きます。

ネットワーク

id を network として渡します。GET /v1/networks は、現在のモードで利用できるネットワークを返します。ネットワークは一時停止されることがあるため、固定で書き込まず、この結果を読んでください。

入金アカウント(固定アドレス) POST /v1/deposit-accounts

POST /v1/deposit-accounts に {"customer_ref": "user_42"} を渡すと、そのお客様に全ネットワークの恒久アドレスが発行されます(すべての EVM チェーンは1つのアドレスを共有)。届いた分はすべて米ドルで計上され、送金ごとに deposit.credited の Webhook が1回届きます。

curl -X POST https://blockwallets.io/v1/deposit-accounts \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"customer_ref":"user_42"}'

{
  "id": "dac_01J8…",
  "mode": "live",
  "customer_ref": "user_42",
  "deposit_url": "https://blockwallets.io/deposit/dac_01J8…",
  "min_amount": 100,
  "currency": "USD",
  "networks": [
    { "id": "USDT_TRC20", "chain": "tron", "token": "USDT", "address": "TXy4…8kQ2", "min_amount": 100, "confirmations": 1, … },
    { "id": "USDC_BASE", "chain": "base", "token": "USDC", "address": "0x5aE1…", "min_amount": 100, "confirmations": 20, … }
  ]
}

• customer_ref:英字、数字、_ . : @ - で 1〜128 文字。同じ値からは常に同じアカウントが返ります。任意の return_url はあなたのドメイン上のもの
• レスポンスには deposit_url(アドレス、QR コード、最近の入金を表示するホスト型ページ)と networks(各ネットワークの id、address、min_amount、confirmations)が含まれます
• 入金の id は dep_ で始まります。amount は米セント、amount_token はコイン数量で、レート付きの通貨には使用した rate が付きます

最低額(通常 $1、BTC $5)未満の送金は below_min として記録され、自動では計上されません。計上が必要な場合はご連絡ください。

Webhook

管理画面(「開発者 › 連携とキー」。Live と Test にはそれぞれ専用の URL とシークレットがあります)の Webhook URL に JSON を POST します。ボディがそのままイベントです。

POST /your/webhook
X-BW-Event: ev_01J8…
X-BW-Delivery: 1
X-BW-Signature: t=1793693052,v1=5f0c9b…

{"id":"ev_01J8…","type":"invoice.paid","created_at":"2026-11-03T08:04:12.000Z","invoice":{"id":"inv_01J8…","ref":"order_1042","status":"paid","amount":4200,…}}

• X-BW-Signature:t=<unix seconds>,v1=<hex>。v1 = HMAC-SHA256(そのモードの Webhook シークレット, t + . + 生のボディ)
• X-BW-Event:イベント id(ev_…)。これで重複を排除します
• X-BW-Delivery:1 から始まる試行回数

解析する前に生のボディで検証し、t がご自身の時計から 300 秒を超えて離れているものは拒否し、比較は定数時間で行ってください。ボディの invoice / deposit は、照会で返るものと同じオブジェクトです。

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), header: X-BW-Signature
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

2xx の応答で配信済みとみなし、それ以外は 1 分後、5 分後、30 分後、2 時間後、12 時間後、24 時間後、24 時間後に再試行します(合計 8 回)。

イベントと再送

GET /v1/events?invoice_id=inv_…(または deposit_id=dep_…)は、1つの請求または入金の Webhook を state、attempts、last_status、last_error とともに一覧します。POST /v1/events/ev_…/redeliver はすぐに再度キューに入れます(エンドポイントを直した直後などに使います)。管理画面の「開発者 › Webhook ログ」では、すべての試行をリクエストとレスポンス付きで確認できます。

テストモード

bw_test_ キーで作成した請求はテストネットで動き、本物のお金は動きません。ホスト型決済ページには「決済をシミュレート」ボタン(全額 / 半額 / 超過払い)が表示されるので、テストネットのコインを用意しなくても、状態の変化と Webhook を確認できます。