Keeper Holdingsと連携するサンドボックス

クイックスタート

サインイン不要のリクエストを3つ。そのあと、下から自分の役割の流れを選んでください。

curl https://keeperholdings.io/v1/skus
curl https://keeperholdings.io/v1/hold/quote?sku=nvidia-rtx-4090&months=3
curl -X POST https://keeperholdings.io/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

ウォレットでサインイン

申請が必要なアカウントはありません。Base Sepolia上のどのウォレットもそのままサンドボックスの認証情報になります。GET /v1/auth/nonce を呼び、EIP-4361形式のメッセージに personal_sign で署名し、POST /v1/auth/verify に送ります。応答にはベアラートークン（kh_s クッキーにも設定）が含まれ、7日間有効です。サインインが必要なルートでは Authorization: Bearer … として使います。

Keeperの流れ

1. サインイン後、display_name と region（ISOの国-地域コード。例 JP-13）を付けて POST /v1/keeper/apply。
2. 保証金を預けます。USDC.approve(bond, amount) の後に KeeperBond.deposit(amount)。保証金がチェーン上に記録されるとステータスが有効になります。カバー率は保管中の価値の110%以上を維持する必要があります。
3. 所有者があなたを選ぶと、GET /v1/keeper/me に INTAKE_PENDING の保管証が現れます。写真で到着を確認します。POST /v1/receipts/{id}/intake（multipartの photo）。Workerが写真を確認し、非公開で保存し、ハッシュ化して、署名付きの受領アテステーションを返します。
4. 所有者が保管証を発行したら CustodyReceipt.acknowledge(id) を呼びます。保管証は HELD になり、報酬のスケジュールが始まります。
5. 期間ごとに POST /v1/receipts/{id}/proof でワンタイムコードを取得し、未開封品の横で撮影して POST /v1/proofs/{pr}/submit。パソコンで作業している場合は、POST /v1/capture/token に { "kind": "intake" | "proof", "id": "kr_… | pr_…" } を送ると、30分間有効なURL（/capture/{kind}/{id}?t=…、QRコードのSVG付き）が返ります。スマートフォンはウォレットなしでそのURLを開き、セッションの代わりに ?t= を付けて同じ2つのルートに送信します。トークンはその保管証または証明リクエスト1件に限定され、どこにも記録されません。合格すると署名付きの ProofAttestation と releaseOnProof のcalldataが返り、誰が送信しても1期間分の報酬があなたに支払われます。確信度の低い判定は審査のため QUARANTINED になります。
6. 配送依頼があれば発送し、markShipped(id, trackingHash) を呼びます。

所有者の流れ

1. GET /v1/hold/quote?sku=…&months=… で区分、証明の間隔、1期間あたりの料金、前払い額を取得します。
2. サインインして sku_id、keeper_id、任意でシリアル番号（ハッシュのみ保存）を付けて POST /v1/hold/request。未開封品をKeeperへ発送します。
3. Keeperが到着を確認すると保管証は VERIFIED になり、GET /v1/hold/mine に受領アテステーションとすぐに使える mint 用のcalldataが含まれます。エスクローにUSDCを承認し、CustodyReceipt.mint(attestation, signature, periods) を呼びます。前払いした料金は FeeEscrow に置かれ、保管証と一緒に移ります。
4. requestRedemption(id) で配送を依頼し、発送後に close(id) で保管証を焼却すると、未精算の料金が返金されます。
5. 売却するには、決済コントラクトに保管証の移転を承認し、EIP-712の Offer に署名して POST /v1/market/offers。買い手がアトミックに約定します。

エージェント向け: MCPとx402

https://keeperholdings.io/mcp のMCPサーバー（JSON-RPC 2.0、Streamable HTTP、SSEなし）は、商品、価格、見積り、Keeper、保管証、オファー、アテステーション、チェーン情報、calldata生成の読み取りツールを無料で提供します。index_live と GET /v1/index/{sku}/live は x402 v2による有料で、料金はBase Sepolia上のテスト用USDC 0.01、ファシリテーターは https://x402.org/facilitator です。資金のあるウォレットを持つエージェントは、APIと自身の署名だけで保管の見積り、保管の申込み、料金の支払い、保管証の売買ができます。

{ "mcpServers": { "keeper-holdings": { "url": "https://keeperholdings.io/mcp" } } }

署名付きアテステーション

Workerがインデックスのオラクルです。GET /v1/attestations は、証明者 0xc948f48082BAE908D803edC53ec1F6753bD056EB が署名したEIP-712の IndexAttestation（skuはIDのkeccak256、価格はUSDCの最小単位、区分、有効期間）を返します。同じ鍵が IntakeAttestation（mint が検証）と ProofAttestation（releaseOnProof が検証）にも署名します。ドメイン: {"name":"Keeper Holdings","version":"1","chainId":84532,"verifyingContract":"0x8e90A4C0b9EC75aeFA76853B6ccBEa7489B24c08"}。

コントラクト（Base Sepolia、チェーンID 84532）

すべてのコントラクトは84532以外のチェーンID（ローカルのanvil用の31337を除く）を拒否します。保管証の移転は HELD の間のみ、かつ transfersOpen が true の間のみ可能です（サンドボックス: 有効。本番: パイロットの条件を満たすまで無効）。運営者の権限は、一時停止、48時間のタイムロック付きの紛争解決、24時間のタイムロック付きの証明者の交代で、いずれも実行のたびにイベントとして記録されます。テスト用のお金: サンドボックスのUSDCは誰でも mint(to, amount) で発行できます（1回5,000まで）。ガス: Base Sepolia向けの任意のフォーセット。

Webhook

サインインして POST /v1/webhooks に { "url": "https://…", "events": ["receipt.state", "proof.result", "offer.posted", "offer.filled", "signal.fired", "signal.cleared"] } を送ります。応答には署名用のシークレットが含まれ、表示は一度だけです。各配信は { id, event, created_at, sandbox, data } のJSON POSTで、X-Keeper-Signature: sha256=HMAC-SHA256(secret, body)、X-Keeper-Event、X-Keeper-Delivery のヘッダーが付きます。10秒以内に2xxを返してください。20回連続で失敗するとそのWebhookは一時停止し、POST /v1/webhooks/{id} に { "status": "active" } を送ると再開します。POST /v1/webhooks/{id}/test でping配信、GET /v1/webhooks/{id}/deliveries で直近50件を確認できます。売却シグナルは、/v1/signals のトリガーの状態が変わったときにインデックスのcronから送られます。ポーリングも引き続き使えます: GET /v1/receipts/{id}、/proofs、/v1/market/offers、/v1/testnet。

OpenAPI

/openapi.json にすべてのルートの定義があります。公開データはCORSで開放され、サインインが必要なルートはベアラートークンを受け付けます。