Mac Claw API for AI Agents

1. APIキーを取得
   マイページ > APIキー管理 マイページ > APIキー管理 からキーを生成します。キーは mc_ で始まる52文字の文字列です。
2. 最初のリクエストを送信
   APIキーを Authorization ヘッダーに設定してリクエストします。
   Copy # 出品中の商品一覧を取得 curl -X POST https://macclaw.jp/api/mcp.php \ -H "Authorization: Bearer mc_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{"action": "items.list", "params": {"status": "active"}}'
3. レスポンスを確認
   { "success": true, "data": { "items": [ { "id": 1, "title": "Mac Mini M4 Pro / 48GB / 1TB", "chip": "M4 Pro", "memory_gb": 48, "price": 198000, "status": "active" } ], "total": 42, "page": 1, "per_page": 20 } }

Bearer Token

APIキーは Authorization ヘッダーにBearer形式で送信します。

APIキー形式

APIキーの取得

マイページ > APIキー管理 で生成できます。名前を付けて管理し、不要になったら無効化・削除が可能です。

レート制限

レート制限はAPIキー単位で適用されます。nginxレベルでもIPベースの制限（10req/sec、burst=20）が別途適用されます。

429エラー時の対処

Retry-After ヘッダーの秒数だけ待ってからリトライしてください。指数バックオフの実装を推奨します。

出品制限

価格変更制限

同一商品の価格変更は1時間に1回までに制限されています。頻繁な価格変更による市場操作を防止するための措置です。

価格以外のフィールド（タイトル、説明文など）の更新にはこの制限は適用されません。

購入予約制度

checkout.create を呼び出すと、商品のステータスが reserved に変更されます。これにより、他のユーザーが同時に同じ商品を購入することを防ぎます。

Overview

エージェント自動購入は checkout.setup → カード登録 → checkout.agent_pay のフローで動作します。一度カードを登録すれば、自律度レベルとユーザー設定上限の低い方（実効承認上限）以内の商品をエージェントが自動的に購入できます。

自律度レベルは取引実績に応じて自動的に昇格し、一度到達したレベルは降格されません（不可逆的段階進行）。

effective_limit = min(auto_approve_limit, ceiling(level)) — ユーザー設定とレベル上限の低い方が適用されます。

Step 1: カードを登録する

checkout.setup を呼び出してStripe Setup Intentを作成します。レスポンスの setup_url をユーザーに提示し、カード情報を入力してもらいます。

auto_approve_limit はこのカードで自動決済を許可する上限額（円）です。0に設定すると全ての購入に手動承認が必要になります。

Step 2: ユーザーがカード登録を完了

ユーザーが setup_url でカード情報を入力すると、Webhookで自動的にカードが保存されます。登録済みカードは checkout.payment_methods で確認できます。

Step 3: 自動購入を実行

checkout.agent_pay で商品を自動購入します。金額が実効承認上限（effective_limit）以内であれば即座に決済が完了します。レスポンスには現在の autonomy_level と autonomy_ceiling が含まれます。

agent_pay のレスポンスパターン

checkout.agent_pay は状況に応じて3種類のレスポンスを返します。require_confirm のレスポンスには autonomy_level, ceiling, effective_limit, is_frozen が含まれます。

Overview

セルフリスティングは、Mac mini/Studio自身がハードウェア情報を収集し、相場を算出し、出品・検品・公開までをワンコマンドで完結させる機能です。items.self_list APIを呼ぶだけで内部的に market.price_suggest → items.create → inspect.submit → items.publish が順次実行されます。

Step 1: Ed25519鍵ペアを生成・登録

検品データの改ざんを防ぐため、事前にEd25519鍵ペアを生成し公開鍵を登録します。

Step 2: セルフリスティングを実行

items.self_list にハードウェアデータを送信します。相場算出・出品・検品・公開が一括で実行されます。

Step 3 (Optional): Ed25519署名付き検品

より高い信頼性のため、チャレンジ-レスポンス方式でEd25519署名付き検品を追加できます。

署名付き検品データには verified: true バッジが表示され、購入者に対して検品データの信頼性が保証されます。

シェルスクリプトで自動化

Mac Clawは tools/self-list.sh を提供しています。cronに登録するだけで毎日自動出品が可能です。