# Verifi Agent API, contract version 2

Verifi sends agent requests to real humans. Human work can take several minutes. The API is asynchronous and resumable through a durable verify_id.

Canonical docs: https://verifi.cloud/docs/
Full reference for LLMs: https://verifi.cloud/llms-full.txt
OpenAPI 3.1 spec: https://verifi.cloud/openapi.json

## Required two-gate flow

1. POST /verify with JSON {intent, claim, agent_id, callback_url?}. agent_id is required and must be the requester 0x wallet address.
2. Gate 1 costs 0.10 USDC through x402. The request does not enter the human queue before settlement. Store verify_id from the 202 response.
3. Prefer callback_url for verify.ready or verify.failed so no active polling loop is needed. Persist verify_id. If callback delivery fails, poll GET /verify/{verify_id}, honor retry_after_seconds, and do not assume a short fixed deadline.
4. If status is failed, stop. failure.entry_credit_granted reports the 0.10 USDC entry credit.
5. If status is ready, POST /verify-unlock?id={verify_id}.
6. Gate 2 is a new 2.90 USDC x402 payment. After settlement the response status is completed and contains the human answer.

Total successful paid price: 0.10 + 2.90 = 3.00 USDC.

## Free and credit funding

Every wallet receives five complete free chains. One initial_free entitlement covers both gate 1 and gate 2. The agent still performs the same submit, poll, and unlock actions. There are no queue, human workflow, timing, status, or response-shape differences between free and paid chains. A free use is counted when a chain completes, so an unanswered free chain does not consume one of the five.

If an admitted chain fails without a redeemable result, what the wallet gets back depends on how gate 1 was funded. If gate 1 was paid with x402, the wallet receives one failure_credit worth 0.10 USDC. It covers gate 1 of the next chain and does not cover gate 2, which still costs 2.90 USDC. If gate 1 was funded by an entitlement, either a free chain or an earlier credit, that entitlement is returned to the wallet instead and no new credit is minted. Read failure.entry_credit_granted to see which happened.

## Statuses

- processing: admission is settling or a human is working. Poll again.
- ready: a human result exists but is locked. Call unlock.
- failed: no redeemable result will be produced. Stop.
- completed: gate 2 passed. Use verdict and explanation.

Human verdict vocabulary: true, false, refined. Refined free text is in explanation and response.

## x402

x402 v2, exact scheme, USDC on Base mainnet eip155:8453. Entry and unlock are separate EIP-3009 authorizations, separate settlements, and separate transaction hashes tied to the same verify_id. The buyer needs no ETH. @x402/fetch can read the 402 requirement, sign it with ExactEvmScheme, and retry automatically. Buyer quickstart: https://docs.x402.org/getting-started/quickstart-for-buyers

## Reliability and rules

- One active chain per wallet.
- Unanswered human work expires after 60 minutes.
- callback_url receives verify.ready or verify.failed and removes the need for an active polling loop. It never carries a locked result. Persist verify_id and use polling as the recovery path.
- No API key, signup, account, or whitelist is required. Just a requester wallet. The wallet identifies free use and signs paid x402 authorizations.
- Queue capacity is checked before gate 1 payment. A 429 or 503 admission response is not charged.
- GET polling never costs money.

## MCP

Endpoint: https://verifi.cloud/mcp

Tools: verify_claim, get_verify, unlock_verify, verifi_info. verify_claim accepts optional callback_url.

Free and paid chains use the same MCP tools. If a gate is paid, the tool returns a standard x402 PaymentRequired result with x402Version, accepts, and the MCP resource. An x402-aware MCP client signs the selected requirement with the requester wallet and repeats the same tool call using x402/payment metadata. A successful paid call returns x402/payment-response metadata. Generic MCP clients can instead pass an encoded authorization through the optional payment_signature argument. Never send a private key. Gate 1 and gate 2 require separate signatures tied to the same verify_id.

## Audit

PostgreSQL stores wallet address, request content, both list prices, both charged amounts, both transaction hashes, lifecycle timestamps, all five free uses, failure credits, their source chains, and their consuming chains. audit_log is append-only.