開発者向け

エージェントが自分ではできない作業を、人に頼めるようにする

店の様子を見に行く、紙の資料を書き起こす、実物を確かめる、電話で問い合わせる。MCP のツールを足すか REST API を呼べば、こうした作業を人に頼めます。人を探す、連絡する、支払うといった手間は ProofMarket が引き受けます。

返ってくるのは答えだけではありません。AI が写真と答えを依頼文と突き合わせた判定、何人の答えが一致したか、Solana に記録した結果と支払いの署名も一緒に返るので、エージェントはその結果を使ってよいかを自分で判断できます。

はじめてなら、3 ステップのページで。キーの受け取りから確認まで 1 ページで終わります。

エージェントをつなぐ →

つなぎ方は3通りあります

どれを選んでも、使えるキーと上限は同じです。API キー(pm_test_ で始まる)は「エージェントをつなぐ」のページでその場に出ます。依頼者の画面(履歴・残高)

claude.ai などのリモート MCP

コネクタの追加画面にこの URL を入れます。接続のときに ProofMarket の画面が開くので、そこで API キーを入れます。

https://proofmarket.fun/mcp

Claude Code などのローカルのエージェント

同じ URL に、API キーをヘッダーで渡して登録します。

claude mcp add --transport http proofmarket https://proofmarket.fun/mcp \
  --header "Authorization: Bearer pm_test_..."

REST API

依頼の作成には Idempotency-Key ヘッダーが要ります。同じキーで送り直しても、依頼は1件しかできません。費用(報酬×人数)は作成した時点で残高から引き当てます。先に費用だけ確かめるなら POST /v1/verifications/quote に同じ本文を送ると、何も引き当てずに quote_id と total と balance_after が返り、5 分以内に quote_id を本文に付けて作成すれば確定します。MCP では request_reality_verification の confirm: false が同じ働きをします。自分の依頼の一覧は GET /v1/verifications です。

curl -X POST https://proofmarket.fun/v1/verifications \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @request.json
curl https://proofmarket.fun/v1/verifications/ver_... \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY"

報酬の通貨

報酬は USDC のほか、この下の一覧にある Solana のトークンでも払えます。bounty.asset に記号を書き、bounty.amount はその通貨の額で書きます。前払いの残高は通貨ごとに分かれていて、依頼の報酬は同じ通貨の残高から引かれます。証人も同じ通貨で受け取ります。通貨の両替はしません。

GET /v1/public/assets      // 認証なし。MCP では list_reward_assets
{
  "network": "solana",
  "assets": [
    { "symbol": "USDC", "mint": "EPjF...Dt1v", "decimals": 6, "amount_decimals": 6, "volatile": false, ... },
    { "symbol": "SOL",  "mint": "So11...1112", "decimals": 9, "amount_decimals": 6, "min_bounty": "0.001", ... },
    { "symbol": "BONK", "decimals": 5, "amount_decimals": 5, "volatile": true, ... }
  ]
}

登録なしで使う(x402)

API キーがなくても、Solana のウォレットを持つエージェントなら依頼を出せます。依頼ごとに USDC を払う方式で、申し込みも契約も要りません。支払いの形式は x402(v2)の exact 方式に従っています。

  1. 依頼をPOST /v1/x402/verificationsに送ります。中身は request.json と同じで、principal_ref は要りません。
  2. 402 が返ります。PAYMENT-REQUIRED ヘッダーに、払う額(報酬×人数)、宛先、通貨(Solana Devnet の USDC)、手数料を持つ側の公開鍵が入っています。中身に問題がある依頼は、払う前に 400 などで断ります。
  3. 指定どおりの USDC の送金取引を作り、自分の鍵で署名します。手数料は ProofMarket が持つので、ウォレットに SOL は要りません。
  4. 同じ依頼を PAYMENT-SIGNATURE ヘッダー付きで送り直します。取引が Solana で確定してから依頼が作られ、201 で verification_id、結果を読むための API キー、支払いの取引の URL が返ります。
# 1回目: 402 と支払い条件
curl -i -X POST https://proofmarket.fun/v1/x402/verifications \
  -H "Content-Type: application/json" -d @request.json

# 2回目: 署名した取引を付けて送り直す
curl -X POST https://proofmarket.fun/v1/x402/verifications \
  -H "Content-Type: application/json" -d @request.json \
  -H "PAYMENT-SIGNATURE: <base64 PaymentPayload>"
# 見本のエージェント(リポジトリの scripts/)。402 の受け取りから結果待ちまで通しで動く
# 17 種類どれでも出せる。種類の一覧は --list-types、送らずに中身を見るなら --dry-run。払う前に条件を見せて y/N を聞き、送る直前に条件を取り直して違えば払わない(--yes で問いだけ省ける)
A="pnpm --filter @proofmarket/scripts run run x402-agent.ts --base-url https://proofmarket.fun"

$A --type DOCUMENT_TRANSCRIPTION --question "届いた紙の請求書の合計金額の行を書き写してください"
$A --type PHONE_INQUIRY --question "この番号の病院に、今日の午後の外来の受付時間を聞いてください"
$A --type MEASUREMENT --unit cm --question "玄関のドアの幅を測ってください"
$A --type CUSTOM_CHOICE --choices "はい,いいえ" --question "この駅のエレベーターは今動いていますか"
$A --type PLACE_STATUS_VERIFICATION --lat 35.6595 --lng 139.7005

同じ取引を2回送っても、依頼は1件しかできません。2回目は同じ verification_id を返し、API キーは付けません。報酬に上限はありません。テスト用の USDC は Circle の faucet(Solana Devnet)で受け取れます。

結果を利用者に見せる(証明のリンク)

エージェントが利用者に答えるとき、「AI の推測ではなく、人が確かめた事実だ」と示せます。

結果が出ると、result.proof に3つの値が入ります。url は公開の結果ページで、いつ・何人が・どう確かめたかと、Solana の記録を誰でも見られます。badge_url は答えと時刻を1行で示す画像、markdown はそのバッジをリンク付きで貼れる文字列です。質問文・写真・位置・文章の答えは、このページに出ません。

"proof": {
  "url": "https://proofmarket.fun/r/ver_01J9Z4K8...",
  "badge_url": "https://proofmarket.fun/r/ver_01J9Z4K8.../badge.svg",
  "markdown": "[![人が確認](https://proofmarket.fun/r/ver_01J9Z4K8.../badge.svg)](https://proofmarket.fun/r/ver_01J9Z4K8...)"
}

結果をみんなの地図に載せる

公共の場所についての事実は、依頼した本人のほかにも役に立ちます。

依頼に "publish": true を付けると、結果が VERIFIED になったときみんなの地図に72時間載ります。公開されるのは、質問文、指定した場所、答え、確かめた時刻と人数です。質問文に個人の事情を書いた依頼には付けないでください。場所のある依頼で、答えが選択か数値のものだけが対象で、それ以外は 400 を返します。一覧は GET /v1/public/map でも読めるので、ほかのエージェントが依頼を出す前に調べる使い方もできます。

判定を、聞かれる前に利用者へ届ける

worker の提出を AI が確かめ、答えが確定しても、エージェントが読みに来なければ利用者は知りません。GET の summary を、そのまま利用者に伝えてください。

  • summary は人向けの 1 段落(ja / en)。引き受け手を待っている、向かっている、AI が確かめ中 n 件、差し戻し n 件、仮の答え、確定した答えと AI の照合の結果、却下の理由、支払いの状態、証明のリンクが入ります
  • witness_progress.checking は AI が確かめている提出の数、returned は依頼と合わず差し戻した数です(worker はその場で直せます)
  • GET /v1/verifications/{id}?wait=45 は、状態が変わるか結果が出るまで最大 45 秒待ってから返します。利用者が待っている間はこれを繰り返し、summary が変わるたびに伝えます。MCP では get_reality_verification の wait_seconds=45
  • 結果が出たら、答えと result.reviews(AI の照合の判定と理由)と result.proof.url を、聞かれる前に返事に含めてください。MCP のツールの説明と応答の note にも同じ指示が書いてあります
GET /v1/verifications/ver_01J9Z4K8...?wait=45

{
  "status": "SUBMITTED",
  "witness_progress": { "valid": 1, "required": 2, "checking": 1, "returned": 0, "active_claims": 1, "open_slots": 0 },
  "summary": {
    "ja": "人の答えが届き始めました。有効な答え 1 / 2 人、AI が写真と答えを確かめている提出が 1 件。2 人の答えがそろうと確定します。",
    "en": "Answers are coming in: 1 of 2 valid; 1 submission under AI review. Final once 2 agree."
  },
  "result": null
}

MCP のツール(8つ)

request_reality_verification
質問を出す。verification_id がすぐ返り、結果は後から読む。wait_seconds で直後の変化を待てる
request_reality_verifications_batch
同じ依頼を多くの場所へ、または違う質問を一度に。最大50件。全件できるか、1件も作らないか
get_reality_verification
状態と結果を読む。wait_seconds(最大45秒)で変化を待てる。summary は利用者にそのまま伝える文
cancel_reality_verification
まだ誰も向かっていない依頼を取り消す。拘束した額は残高に戻る
dispute_reality_verification
結果に異議を出す。確定から24時間以内に1回だけ。同じ場所・同じ質問の再確認(既定は2人一致)を新しく作る
watch_reality_verification
見守りを始める。望む答えが返るまで決めた間隔で確かめ続け、合ったら止まる。回数の上限も付けられる
list_reality_verification_watches
見守りと定期確認の一覧。止まった理由と、条件に合った依頼の ID が分かる
stop_reality_verification_watch
見守りや定期確認を止める。すでに作られた依頼はそのまま進む

人が現地まで行くので、結果が出るまでふつう10〜60分かかります。状態が VERIFIED・REJECTED・EXPIRED のどれかになるまで、エージェントに答えを推測させないでください。

プログラムから読める事実(On-chain facts)

結果は Solana の Task 口座に 1 行で残ります。保険や予約のプログラムは、それを直接読んで動けます。

口座の場所(PDA)と読み方は GET /v1/public/verifications/{id}/onchain が返します。TypeScript なら packages/sdk の verifyOnChain が、結果から result_hash を計算し直して口座の値と比べます。Rust は Anchor の AccountDeserialize で Task を読みます。保険の自動支払いと予約の切り替えの例は docs/onchain-facts.md にあります。

依頼の中身

request.json の例です。principal_ref は API キーと一緒に渡される ID です。

{
  "type": "PLACE_STATUS_VERIFICATION",
  "question": "この店はいま営業していますか?",
  "answer_schema": { "type": "enum", "values": ["OPEN", "CLOSED", "UNCLEAR"] },
  "location": { "lat": 35.6595, "lng": 139.7005, "radius_m": 80 },
  "deadline": "2026-10-12T12:00:00+09:00",
  "evidence_requirements": { "photo": true, "task_nonce": true },
  "assurance": { "level": "standard" },
  "bounty": { "asset": "USDC", "amount": "0.5", "network": "solana-devnet" },
  "principal_ref": "prn_..."
}
question
確かめたいこと・してほしい作業。1000字まで。本なら書名・ページ・箇所まで書く
type
PLACE_STATUS_VERIFICATION(営業しているか)、QUEUE_LENGTH(店の外の行列)、NOTICE_POSTED(店頭の掲示)、CROWD_LEVEL(混み具合)、SEAT_AVAILABILITY(空席)、PARKING_AVAILABILITY(駐車場の空き)、STOCK_CHECK(在庫)、PRICE_CHECK(値段)、SIGN_TRANSCRIPTION(掲示・メニューの書き起こし)、SITE_REPORT(現地の様子の報告)、DOCUMENT_TRANSCRIPTION(本・紙資料の書き起こし)、DOCUMENT_QA(本・紙資料を読んで答える)、PRODUCT_INSPECTION(実物の確認)、PHONE_INQUIRY(電話での問い合わせ)、MEASUREMENT(計測)、CUSTOM_CHOICE(選んで答える質問)、CUSTOM_TASK(その他の作業)、SENSORY_REPORT(五感の報告)。API キーごとに使える種類を絞れる
answer_schema
答えの形。type ごとに決まっている。選択式は { "type": "enum", "values": [...] }(PLACE_STATUS_VERIFICATION: OPEN・CLOSED・UNCLEAR, QUEUE_LENGTH: NO_QUEUE・SHORT_QUEUE・LONG_QUEUE・UNCLEAR, NOTICE_POSTED: POSTED・NOT_POSTED・UNCLEAR, CROWD_LEVEL: EMPTY・MODERATE・CROWDED・UNCLEAR, SEAT_AVAILABILITY: SEATS_AVAILABLE・FULL・UNCLEAR, PARKING_AVAILABILITY: SPACES_AVAILABLE・FULL・UNCLEAR, STOCK_CHECK: IN_STOCK・OUT_OF_STOCK・UNCLEAR から2個以上。CUSTOM_CHOICE は自分で6個まで決める)。数値は { "type": "number", "unit": "円" }(PRICE_CHECK・MEASUREMENT)。文章は { "type": "text", "max_chars": 2000 }(ほかの種類)。文章の種類では、複数の項目をまとめて受け取る { "type": "form", "fields": [{ "key": "price", "label": "値段", "type": "number", "unit": "円" }, ...] } も使える(8項目まで。答えは項目ごとの値を持つ JSON が 1 人 1 つ)。文章と form の答えは結果の answers に全員分が入り、answer にはその SHA-256 が入る。form の項目には尺度 { "type": "scale", "key": "noise", "label": "騒音", "max": 5, "labels": ["静か", "うるさい"] } も使える(max は 5 か 10。worker には丸が横に並び、言葉は両端だけに出る。3 人以上の答えがそろうと、結果の aggregate に項目ごとの中央値・最小・最大が入る)
acceptance_criteria
受け取りの条件(任意、500字まで)。「値札の数字が読める写真であること」「店名が写っていること」のように書く。worker には質問文の下に出て、AI の照合にも質問文と一緒に渡る
attestation
エージェント自身がしたことを、人に確かめてもらう(任意)。{ "subject": "agent_action", "description": "302号室に荷物を届けた" } のように書く(description は200字まで)。worker には「AI エージェントが『…』と言っています」と出て、証明ページの見出しは「『…』が本当だと、人が確かめました」になる。検査と判定はふつうの依頼と同じ
location
緯度・経度と半径(25〜500m)。現地で行う種類では必須。本・電話・実物の確認など、場所を問わない種類では省ける
deadline
締め切り。今から10分後〜24時間後。場所を省いた依頼は7日後まで
freshness.max_age_seconds
写真が撮られてから何秒以内なら有効か。60〜3600秒、既定は300秒
assurance
何人に確かめてもらうか(required_witnesses、最大5人)と、何人の答えがそろえば確定か(quorum)。{ "level": "fast" | "standard" | "high" } と書けば、それぞれ1人・2人一致・3人中2人になる
bounty
1人あたりの報酬。Solana Devnet の USDC
bounty.max_amount・ramp_minutes(任意)
報酬の上限と、上がりきるまでの分数(10〜1440、既定は締切まで)。報酬は amount から直線で上がり、最初に誰かが引き受けた時点の額で全員分が決まる。作成時に max_amount × 人数を引き当て、使わない分はその時点で残高に戻る。x402 では使えない
worker_requirements(任意)
{ "min_tier": "standard" | "trusted" } で、引き受けられる worker を記録の良い人に絞る。trusted は有効な提出が10件以上で、複数人の依頼での一致率が90%以上の人

結果の読み方

status が次の3つのどれかになったら確定です。確定までの途中の状態(OPEN、CLAIMED など)では result は null です。

VERIFIED
quorum 以上の答えがそろった。answer に答えが入る
REJECTED
答えが割れた(NO_CONSENSUS)か、有効な証言が足りなかった
EXPIRED
締め切りまでに確定しなかった。拘束した額は返金される

result には答えのほかに、有効な証言の数、一致率、場所・鮮度・写真の使い回しなどの確認結果、Solana に記録した証拠のハッシュと取引の URL が入ります。写真を見たいときは、自分の依頼に限ってGET /v1/verifications/{id}/evidenceで5分間だけ有効な URL を取れます。店舗が自分で「本日臨時休業」などと申告していれば、GET の store_report に参考として入ります。判定には使っていません。

結果を待たずに受け取る(Webhook)

送り先の URL は運営者が登録します。本文には ProofMarket-Signature ヘッダーで署名が付き、5分以上ずれたものは捨ててください。

  • verification.open
  • verification.claimed
  • verification.submitted
  • verification.verified
  • verification.rejected
  • verification.settled
  • verification.expired
  • verification.cancelled
  • verification.provisional
  • verification.challenged
  • task.application_received
  • task.seat_assigned
  • task.submitted
  • task.changes_requested
  • task.released
  • task.rejected
  • task.seat_expired
  • task.message_received

結果に納得できないとき

確定から24時間以内なら、1回だけ異議を出せます。同じ場所・同じ質問で、新しく再確認の依頼が作られます。費用はふつうの依頼と同じで、元の結果と支払いはそのまま残ります。

curl -X POST https://proofmarket.fun/v1/verifications/ver_.../dispute \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "閉店の張り紙を見た", "assurance": { "level": "high" } }'

返る recheck_verification_id をふつうの依頼と同じように読みます。元の依頼の GET には recheck が付き、再確認の答えが元と同じだったか(matches_original)が分かります。違ったときは運営者が元の提出を見直します。

少し前の結果があれば、それを受け取る

依頼に reuse を付けると、同じ店について少し前に確定した結果を探し、あれば人を出さずにその場で返します。待ち時間がなく、費用もかかりません。

"reuse": { "max_age_seconds": 600 },   // 10分以内の結果があれば使う
"allow_reuse": true                     // 自分の結果をほかの依頼者に使わせてよい

使われるのは、元の依頼者が allow_reuse を付けた結果だけです。店・種類・答えの選択肢が同じで、VERIFIED のものに限ります。見つかれば 200 で reused: true と結果そのものが返り、新しい依頼は作られません。NOTICE_POSTED は質問ごとに見る掲示が違うので対象外です。

同じ依頼を、多くの場所へ一度に

棚の確認を50店舗へ、同じ値段の質問を街じゅうへ、1つの場所に違う質問をいくつも。1回の呼び出しで最大50件の依頼を作れます。

POST /v1/verifications/batch      // Idempotency-Key は1つ
{
  "template": { ...request.json から question と location を除いたもの },
  "items": [
    { "location": { "lat": 35.6595, "lng": 139.7005, "radius_m": 80 }, "question": "A店に○○はあるか" },
    { "location": { "lat": 35.6600, "lng": 139.7000, "radius_m": 80 }, "question": "B店に○○はあるか" }
  ]
}

件ごとに template と重ねて、ふつうの依頼と同じ検査を順に行います。1件でも通らなければ全体を断り、何も作りません(details.index に何件目かが入ります)。残高は合計で見ます。応答の verifications は items の順で、それぞれ別の verification_id として追えます。MCP では request_reality_verifications_batch が同じことをします。

店の雰囲気を 3 人で測る

匂い・騒音・清潔感・明るさのように、写真だけでは伝わらない感覚も頼めます。3 人に、1〜5 の尺度で答えてもらいます。

{
  "type": "SITE_REPORT",
  "question": "カフェ○○の店内の雰囲気を、4 つの尺度で答えてください",
  "answer_schema": { "type": "form", "fields": [
    { "type": "scale", "key": "smell", "label": "匂い",   "max": 5, "labels": ["気にならない", "強い"] },
    { "type": "scale", "key": "noise", "label": "騒音",   "max": 5, "labels": ["静か", "うるさい"] },
    { "type": "scale", "key": "clean", "label": "清潔感", "max": 5, "labels": ["汚れている", "きれい"] },
    { "type": "scale", "key": "light", "label": "明るさ", "max": 5, "labels": ["暗い", "明るい"] }
  ] },
  "acceptance_criteria": "店内の様子が分かる写真であること。人の顔は大きく写さないこと",
  "location": { "lat": 35.6595, "lng": 139.7005, "radius_m": 80 },
  "assurance": { "level": "high" },
  ...残りは request.json と同じ
}

3 人の答えがそろうと、result.aggregate に尺度ごとの { median, min, max, n } が入ります。人数が偶数のときの中央値は小さい方を取るので、整数のままです。多数決はしません。判定は文章の答えと同じです。aggregate は result_hash に含まれます。

決まった時刻に繰り返し確かめる

「平日の朝 9 時に、この店が開いているか」のような確認は、予定として登録できます。時刻が来るたびに通常の依頼が1件作られるので、残高や上限、確認の手順はふつうの依頼と同じです。

curl -X POST https://proofmarket.fun/v1/schedules \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": { ...request.json から deadline を除いたもの },
    "deadline_minutes": 30,
    "times_jst": ["09:00"],
    "days_jst": [1, 2, 3, 4, 5]
  }'

時刻は日本時間、曜日は 0 が日曜です。できた依頼は Webhook か GET /v1/schedules の last_verification_id で追えます。残高不足などで3回続けて作れなかった予定と、API キーが止められた予定は自動で止まります。止めるときは DELETE /v1/schedules/{id} を呼びます。1つのキーで動かせる予定は10件までです。

望む答えが返るまで見守る

「エレベーターが復旧したら知らせて」「棚に入荷したら知らせて」のような依頼は、見守りとして登録できます。決めた間隔で確かめ続け、条件に合う答えが確定したら止まります。

curl -X POST https://proofmarket.fun/v1/schedules \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": { ...STOCK_CHECK の依頼。deadline は除く },
    "deadline_minutes": 60,
    "every_minutes": 120,                 // 2時間おき。最初の1回はすぐ
    "max_runs": 12,                       // 多くても12回で止まる
    "stop_when": { "answer": "IN_STOCK" } // この答えが確定したら止まる
  }'

1回ごとに通常の依頼が作られ、そのぶんだけ払います。条件は、選択で答える依頼なら { "answer": ... } か { "answer_in": [...] }、数値で答える依頼なら { "number": { "min": 1 } } のように書きます。文章で答える依頼には付けられません。条件に合うと、その依頼の verification.verified の Webhook が届き、GET /v1/schedules の stopped_reason が condition_met、matched_verification_id に合った依頼の ID が入ります。MCP では watch_reality_verification で同じことができます。

上限と支払い

報酬の額には、1件あたりにも1日あたりにも上限がありません。残高が足りる限り依頼できます。制限するのは、API キーごとの1分あたりの呼び出し回数だけです。依頼を出すと、報酬×人数の額が前払いの残高から拘束され、確定すると worker に支払われます。期限切れや取り消しのときは残高に戻ります。残高は Solana Devnet の USDC です。