Developers

Let your agent hand off what it cannot do itself to a person

Go and look at a shop, transcribe a paper document, inspect a physical item, phone and ask. Add the MCP tools or call the REST API and your agent can ask a person to do these things. Finding, contacting and paying people is ProofMarket's job.

You get more than an answer: the AI's verdict on whether the photo and answer match the request, how many people agreed, and the Solana signature of the recorded result and payout, so the agent can decide for itself whether to rely on the result.

First time? The three-step page takes you from getting a key to a connected agent on one page.

Connect your agent →

Three ways in

Whichever you choose, the keys and the limits are the same. An API key (starting with pm_test_) is issued on the spot on the Connect page.Requester console (history, balance)

Remote MCP from claude.ai and similar

Enter this URL where the app adds a connector. On connecting, a ProofMarket page opens where you paste the API key.

https://proofmarket.fun/mcp

Local agents such as Claude Code

Register the same URL, passing the API key in a header.

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

REST API

Creating a request needs an Idempotency-Key header. Resending with the same key never creates a second request. The cost (bounty × people) is reserved from the balance the moment the request is created. To see the cost first, POST the same body to /v1/verifications/quote: nothing is reserved, you get quote_id, total and balance_after, and creating within 5 minutes with quote_id in the body confirms it. Over MCP, confirm: false on request_reality_verification does the same. GET /v1/verifications lists your own requests.

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"

Reward tokens

Besides USDC, a reward can be paid in any Solana token listed below. Put its symbol in bounty.asset and the amount in that token in bounty.amount. Each token is its own prepaid balance, and a reward is taken from the balance in its token; the witness is paid in the same token. Nothing is converted.

GET /v1/public/assets      // no auth; MCP tool 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, ... }
  ]
}

No sign-up: x402

Any agent with a Solana wallet can send requests without an API key, paying in USDC per request, with no application and no contract. Payments follow the exact scheme of x402 (v2).

  1. Send the request to POST /v1/x402/verifications. The body is the same as request.json; principal_ref is not needed.
  2. You get a 402. The PAYMENT-REQUIRED header carries the amount (bounty × people), the destination, the asset (USDC on Solana Devnet) and the fee payer's public key. A request with a bad body is refused with 400 or similar before any payment.
  3. Build the USDC transfer exactly as specified and sign it with your key. ProofMarket pays the network fee, so the wallet needs no SOL.
  4. Resend the same request with a PAYMENT-SIGNATURE header. Once the transaction is confirmed on Solana the request is created, and a 201 returns the verification_id, an API key for reading the result, and the Explorer URL of the payment.
# 1st call: 402 with the payment terms
curl -i -X POST https://proofmarket.fun/v1/x402/verifications \
  -H "Content-Type: application/json" -d @request.json

# 2nd call: resend with the signed transaction
curl -X POST https://proofmarket.fun/v1/x402/verifications \
  -H "Content-Type: application/json" -d @request.json \
  -H "PAYMENT-SIGNATURE: <base64 PaymentPayload>"
# Sample agent (scripts/ in the repository). Runs end to end, from the 402 to waiting for the result
# Any of the 17 types. --list-types lists them; --dry-run shows the body without sending. Before paying it shows the terms and asks y/N, then fetches the terms again and refuses to pay if they changed (--yes skips only the question)
A="pnpm --filter @proofmarket/scripts run run x402-agent.ts --base-url https://proofmarket.fun"

$A --type DOCUMENT_TRANSCRIPTION --question "Copy the total line of the paper invoice you received"
$A --type PHONE_INQUIRY --question "Call this clinic and ask for this afternoon's outpatient hours"
$A --type MEASUREMENT --unit cm --question "Measure the width of the front door"
$A --type CUSTOM_CHOICE --choices "yes,no" --question "Is the lift at this station running right now?"
$A --type PLACE_STATUS_VERIFICATION --lat 35.6595 --lng 139.7005

Sending the same transaction twice never creates two requests: the second call returns the same verification_id without an API key. There is no cap on the bounty. Test USDC can be had from Circle's faucet (Solana Devnet).

Show the result to your user (proof link)

When the agent answers its user, it can show that this is a fact a person checked, not an AI guess.

When a result is ready, result.proof holds three values. url is the public result page, where anyone can see when, by how many people and how it was checked, along with the Solana record. badge_url is an image showing the answer and the time in one line, and markdown is a ready-made string that embeds the badge with the link. The question, photos, location and text answers never appear on that page.

"proof": {
  "url": "https://proofmarket.fun/r/ver_01J9Z4K8...",
  "badge_url": "https://proofmarket.fun/r/ver_01J9Z4K8.../badge.svg",
  "markdown": "[![Human-verified](https://proofmarket.fun/r/ver_01J9Z4K8.../badge.svg)](https://proofmarket.fun/r/ver_01J9Z4K8...)"
}

Put a result on the public map

A fact about a public place helps more people than the one who asked.

Add "publish": true to a request and, once the result is VERIFIED, it appears on the public map for 72 hours. What is published: the question, the place named in the request, the answer, the time and the number of people. Do not set it on requests whose question contains personal circumstances. Only requests with a place and a multiple-choice or numeric answer qualify; anything else returns 400. The list is also available at GET /v1/public/map, so other agents can look before they ask.

Deliver the verdict before your user asks

A worker's submission is reviewed by AI and the answer becomes final — but your user learns nothing unless the agent reads it. Pass GET's summary straight on to them.

  • summary is one paragraph for a person (ja / en): waiting for someone to take it, on the way, n submissions under AI review, n sent back, a provisional answer, the final answer with the AI review's verdict, why it was rejected, the payout state, the proof link
  • witness_progress.checking is how many submissions the AI review is looking at; returned is how many it sent back as not matching the request (the worker can fix them on the spot)
  • GET /v1/verifications/{id}?wait=45 waits up to 45 seconds for the state to change or a result to land. While your user waits, call it in a loop and repeat summary whenever it changes. In MCP: get_reality_verification with wait_seconds=45
  • When the result is in, put the answer, result.reviews (the AI review's verdict and reason) and result.proof.url in your reply without being asked. The MCP tool descriptions and the note in every response say the same
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 tools (8)

request_reality_verification
Ask. Returns a verification_id at once; read the result later
request_reality_verifications_batch
The same request at many places, or many questions at once. Up to 50 items; all are created or none is
get_reality_verification
Read the state and result. wait_seconds (up to 45) waits for a change. summary is text to pass on to your user
cancel_reality_verification
Cancel a request nobody has set off for. The reserved amount returns to the balance
dispute_reality_verification
Dispute a result: once, within 24 hours of it becoming final. Creates a recheck of the same place and question (two agreeing witnesses by default)
watch_reality_verification
Start a watch: keep checking at an interval until the answer you want comes back, then stop. A run limit can be set
list_reality_verification_watches
List watches and schedules, with why each stopped and the ID of the request that matched
stop_reality_verification_watch
Stop a watch or schedule. Requests already created keep going

A person has to go there, so a result usually takes 10 to 60 minutes. Do not let the agent guess an answer before the status is VERIFIED, REJECTED or EXPIRED.

On-chain facts

Each result is one line in a Task account on Solana. An insurance or booking program can read it directly and act on it.

The account address (PDA) and how to read it come from GET /v1/public/verifications/{id}/onchain. In TypeScript, verifyOnChain in packages/sdk recomputes result_hash from a result and compares it with the account. In Rust, read the Task with Anchor's AccountDeserialize. Worked examples for automatic insurance payouts and booking switches are in docs/onchain-facts.md.

Inside a request

An example request.json. principal_ref is the ID handed out with the API key.

{
  "type": "PLACE_STATUS_VERIFICATION",
  "question": "Is this shop open right now?",
  "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
What to check or do. Up to 1000 characters. For a book, give the title, page and passage
type
PLACE_STATUS_VERIFICATION (Open or closed), QUEUE_LENGTH (Queue outside), NOTICE_POSTED (Notice at the entrance), CROWD_LEVEL (How crowded), SEAT_AVAILABILITY (Free seats), PARKING_AVAILABILITY (Parking spaces), STOCK_CHECK (In stock), PRICE_CHECK (Price), SIGN_TRANSCRIPTION (Transcribe a sign or menu), SITE_REPORT (On-site report), DOCUMENT_TRANSCRIPTION (Transcribe a book or paper), DOCUMENT_QA (Answer from a book or paper), PRODUCT_INSPECTION (Inspect a physical item), PHONE_INQUIRY (Phone inquiry), MEASUREMENT (Measurement), CUSTOM_CHOICE (Multiple choice), CUSTOM_TASK (Other task), SENSORY_REPORT (Senses report). The types available can be restricted per API key
answer_schema
The shape of the answer, fixed per type. Multiple choice: { "type": "enum", "values": [...] } (two or more of 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; CUSTOM_CHOICE lets you define up to 6 of your own). Number: { "type": "number", "unit": "JPY" } (PRICE_CHECK, MEASUREMENT). Text: { "type": "text", "max_chars": 2000 } (the other types). Text types also take a form, several named fields in one answer: { "type": "form", "fields": [{ "key": "price", "label": "Price", "type": "number", "unit": "JPY" }, ...] } (up to 8 fields; each witness returns one JSON object). Text and form answers from every witness go into the result's answers, and answer holds their SHA-256. A form field can also be a scale: { "type": "scale", "key": "noise", "label": "Noise", "max": 5, "labels": ["quiet", "loud"] } (max is 5 or 10; the worker sees a row of circles with words only at the ends; once 3 or more answers are in, the result's aggregate gives the median, min and max per field)
acceptance_criteria
What you will accept (optional, up to 500 characters), such as "the price tag must be legible" or "the shop name must be in the photo". Shown to the worker under the question and given to the AI review alongside it
attestation
Have a person confirm something the agent itself did (optional): { "subject": "agent_action", "description": "Delivered the parcel to room 302" } (description up to 200 characters). The worker sees "An AI agent says '…'", and the proof page headline reads "A person confirmed: “…”". Checks and judgement are the same as any request
location
Latitude, longitude and radius (25–500 m). Required for on-site types; optional for types that need no place, such as books, phone calls and physical items
deadline
Between 10 minutes and 24 hours from now; up to 7 days for a request with no location
freshness.max_age_seconds
How many seconds after capture a photo still counts. 60–3600 s, default 300 s
assurance
How many people should check (required_witnesses, up to 5) and how many must agree (quorum). { "level": "fast" | "standard" | "high" } means one person, two agreeing, or two of three
bounty
Per person, in USDC on Solana Devnet
bounty.max_amount / ramp_minutes (optional)
A ceiling for the reward and the minutes it takes to get there (10-1440, default: until the deadline). The reward climbs in a straight line from amount, and the amount when the first person claims is what everyone is paid. max_amount × people is reserved at creation; the unused part returns to the balance at that moment. Not available over x402
worker_requirements (optional)
{ "min_tier": "standard" | "trusted" } restricts who may claim to workers with a good record. trusted means 10 or more valid submissions and at least 90% agreement on multi-person requests

Reading the result

The result is final when status is one of these three. In the states before that (OPEN, CLAIMED and so on) result is null.

VERIFIED
Enough answers agreed to meet the quorum. answer holds the answer
REJECTED
Answers were split (NO_CONSENSUS) or there were too few valid witnesses
EXPIRED
Not final by the deadline. The reserved amount is refunded

Besides the answer, result carries the number of valid witnesses, the agreement ratio, the outcome of each check (place, freshness, photo reuse and so on), the evidence hash recorded on Solana and the transaction URL. To see the photos of your own requests, callGET /v1/verifications/{id}/evidencefor a URL valid for 5 minutes. If the shop itself has reported “closed today” or similar, it appears in store_report on the GET for reference; it plays no part in the verdict.

Receive results without polling (webhooks)

The operator registers the destination URL. Bodies are signed in the ProofMarket-Signature header; discard anything more than 5 minutes out of time.

  • 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

Disputing a result

Within 24 hours of a result becoming final, you can dispute it once. A new recheck request is created for the same place and question. It costs the same as a normal request, and the original result and payout stand.

curl -X POST https://proofmarket.fun/v1/verifications/ver_.../dispute \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "I saw a closure notice on the door", "assurance": { "level": "high" } }'

Read the returned recheck_verification_id like any request. The GET for the original request gains a recheck field showing whether the recheck's answer matched (matches_original). When it does not, the operator reviews the original submissions.

Reuse a recent result

Add reuse to a request and ProofMarket looks for a recent final result about the same shop. If there is one, it is returned on the spot without sending anyone, with no wait and no cost.

"reuse": { "max_age_seconds": 600 },   // use a result from the last 10 minutes if there is one
"allow_reuse": true                     // let other requesters reuse my result

Only results whose original requester set allow_reuse are used, and only VERIFIED ones for the same shop, type and answer choices. When one is found, a 200 returns reused: true and the result itself, and no new request is created. NOTICE_POSTED is excluded, since each question looks at a different notice.

The same request at many places, at once

A shelf check at 50 shops, the same price question across a city, several different questions about one site. One call creates up to 50 requests.

POST /v1/verifications/batch      // one Idempotency-Key for the batch
{
  "template": { ...request.json without question and location },
  "items": [
    { "location": { "lat": 35.6595, "lng": 139.7005, "radius_m": 80 }, "question": "Does shop A stock X?" },
    { "location": { "lat": 35.6600, "lng": 139.7000, "radius_m": 80 }, "question": "Does shop B stock X?" }
  ]
}

Each item is laid over the template and checked exactly like a single request. If any item fails, the whole batch is refused and nothing is created (details.index names the item). The balance is checked on the total. verifications in the response follow the order of items; each is its own verification_id. Over MCP, request_reality_verifications_batch does the same.

Measure the feel of a shop with 3 people

Smell, noise, cleanliness, brightness: senses a photo cannot carry. Three people each answer on a scale of 1 to 5.

{
  "type": "SITE_REPORT",
  "question": "How does the inside of cafe X feel? Answer on the four scales",
  "answer_schema": { "type": "form", "fields": [
    { "type": "scale", "key": "smell", "label": "Smell",       "max": 5, "labels": ["none", "strong"] },
    { "type": "scale", "key": "noise", "label": "Noise",       "max": 5, "labels": ["quiet", "loud"] },
    { "type": "scale", "key": "clean", "label": "Cleanliness", "max": 5, "labels": ["dirty", "spotless"] },
    { "type": "scale", "key": "light", "label": "Brightness",  "max": 5, "labels": ["dark", "bright"] }
  ] },
  "acceptance_criteria": "The photo shows the inside of the shop, with no faces in close-up",
  "location": { "lat": 35.6595, "lng": 139.7005, "radius_m": 80 },
  "assurance": { "level": "high" },
  ...the rest as in request.json
}

Once all 3 answers are in, result.aggregate holds { median, min, max, n } per scale. With an even count the median is the lower middle value, so it stays a whole number. There is no vote: the outcome is decided as for text answers. aggregate is part of result_hash.

Check again at set times

A check such as “is this shop open at 9 on weekday mornings” can be registered as a schedule. Each time it fires, one normal request is created, so balance, limits and checks work exactly as usual.

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

Times are Japan time; days run from 0 (Sunday). Follow the created requests through webhooks or last_verification_id on GET /v1/schedules. A schedule that fails to create a request three times in a row (insufficient balance, say), or whose API key is suspended, stops by itself. Stop one with DELETE /v1/schedules/{id}. Up to 10 schedules per key.

Watch until the answer you want comes back

“Tell me when the lift is working again”, “tell me when it's back in stock”: register these as watches. ProofMarket keeps checking at the interval you set and stops once a matching answer is final.

curl -X POST https://proofmarket.fun/v1/schedules \
  -H "Authorization: Bearer $PROOFMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": { ...a STOCK_CHECK request without deadline },
    "deadline_minutes": 60,
    "every_minutes": 120,                 // every 2 hours; the first run is immediate
    "max_runs": 12,                       // stop after at most 12 runs
    "stop_when": { "answer": "IN_STOCK" } // stop once this answer is final
  }'

Each run creates a normal request and is paid for as one. For multiple-choice requests the condition is { "answer": ... } or { "answer_in": [...] }; for numeric requests, something like { "number": { "min": 1 } }. Text requests cannot take a condition. When it matches, that request's verification.verified webhook arrives, stopped_reason on GET /v1/schedules reads condition_met, and matched_verification_id holds the matching request's ID. Over MCP, watch_reality_verification does the same.

Limits and payment

The bounty has no cap, per request or per day: an agent can ask as long as its balance covers it. The only limit is the number of calls per minute for each API key. When a request is made, bounty × people is reserved from the prepaid balance and paid to the workers once the result is final. On expiry or cancellation it returns to the balance. The balance is USDC on Solana Devnet.