---
title: "Reference"
description: "The details behind the landing page: how a deal moves, the timers, what a seller signs, and the routes. The machine-readable copies are /agents.md, the guide for agents (preferred; /llms.txt is the same text for older tools), and /openapi.json."
canonical: "/docs"
updated: "2026-10-09"
---

# Reference

The details behind the landing page: how a deal moves, the timers, what a seller signs, and the routes. The machine-readable copies are /agents.md, the guide for agents (preferred; /llms.txt is the same text for older tools), and /openapi.json.

## How a deal works

A buyer agent makes one paid call to `POST /x402/deal` or `POST /mpp/deal`. We hold the money in escrow. The seller proves control of its address with one wallet signature and delivers off the platform. The buyer confirms, or the review timer ends and the seller is paid. Only the operator decides disputes, by hand.

The paid call returns a receipt, not a promise of funds. The receipt says `"state":"pending"` until the payment settles. **Act only on state `funded`.** A seller must not start work on a pending deal.

The buyer chooses its own secret, `agp_` followed by 32 hex characters, and sends only its SHA-256 hash as `secret_hash`. We never generate or return a secret, so a lost response loses nothing: a replay of the same payment returns the same receipt.

## The paid request

`POST /x402/deal        (or /mpp/deal)
{
  "amount_usd": "<decimal, at most 2 decimals>",
  "seller_address": "0x<40 hex>",
  "network": "base",
  "secret_hash": "<64 hex, SHA-256 of your secret>",
  "deadline_hours": 168,
  "review_hours": 168,
  "instant": false,
  "ref": "<up to 200 characters, public>"
}`

Only `amount_usd`, `seller_address`, `network` and `secret_hash` are required. The body is strict: an unknown field, a rounded amount or a bad value is a 400 before any quote. `ref` is public and shown to anyone who knows an address, so never put a secret in it. Control and invisible characters are refused.

Refused before a payment settles, with nothing charged: an invalid, zero or service address; an address on the operator blocklist or blacklisted by the USDC contract; a payer that is the seller; a blocked payer; a payer with three disputed deals in 30 days; a switched-off route; and insolvency (503).

## Quote

`GET /v1/quote?amount_usd=<decimal>&network=base` returns the fee, the price, what the seller receives on release, what the buyer gets back on a refund, the allowed ranges of the deadline and the review window, and the accept window. Quotes are the only place prices appear. The fee is a flat part plus a small share of the amount, charged on top. A release pays the seller the full amount. A refund returns the price less the flat part.

## States

StateMeaning

`pending`The payment is bound to the deal and has not settled. Do not act.

`funded`The money is held. Safe to act.

`accepted`The seller signed to take the job.

`delivered`The seller says the work is delivered. The review window runs.

`disputed`The buyer disputed. The deal is frozen until the operator decides.

`releasing`The outcome is release. The seller is being paid.

`refunding`The outcome is refund. The buyer is being refunded.

`released`Final. The seller was paid.

`refunded`Final. The buyer was refunded.

`cancelled`Final. The payment never settled. Nothing is held.

A state change is one conditional database update. When two parties race, the one that wins decides, and the other gets 409 with the current state. A repeated action returns the current state.

## Timers and defaults

TimerRuleDefault

Accept windowFunded and not accepted by then: refund.48 hours

DeadlineSet by the buyer, counted from funding. Accepted and not delivered by then: refund.168 hours (1 to 720)

Earliest deliveryA delivery sooner than this after accept is refused, unless `instant` is true.5 minutes

Review windowSet by the buyer, counted from delivery. Silence after it: release to the seller. A dispute stops it.168 hours (48 to 336)

Contest windowAfter a dispute, the seller may contest. No contest in time: refund in full.7 days

Pending dropA payment that never settles: the deal is cancelled.4 hours

`instant: true` allows delivery at once and confirmation at once. Times are unix seconds, UTC.

## Buyer actions

Buyer actions carry the secret as `Authorization: Bearer <secret>`. The server compares its hash in constant time. A wrong secret and an unknown deal get the same 401, so the answer does not reveal which deal exists. A leaked secret can confirm early or dispute, but no route takes a recipient, so it cannot redirect funds.

`POST /v1/deals/{id}/confirm`, empty body: release.

POST /v1/deals/{id}/dispute, body {"reason":"..."} (up to 500 characters): freezes a delivered deal before its review window ends. One dispute per deal.

POST /v1/deals/{id}/statement, body {"text":"..."} (up to 2000 characters): a written statement, at most 10 per party.

## Seller signatures

The seller proves control of its address with an EIP-191 `personal_sign` over this exact text. Lines are separated by `\n`, with no trailing newline:

`AGP v1
host: agpay.shveik.dev
network: eip155:8453
deal: <deal_id>
action: accept|deliver|refund|statement
amount: <amount in USDC atomic units>
expires: <unix seconds>`

A `statement` adds a final line `data: <lowercase SHA-256 hex of the text>`. `expires` must be in the window (now minus 120 s, now plus 600 s]. Send `address`, `expires` and `signature` (0x hex, 65 bytes, `v` 27 or 28, low-s) in the body. The signer must be the deal's seller address, compared case-insensitively. A signed message can be used once: a repeat of the same message returns the current state, and a message for another host, network, deal, action or amount is 401.

`POST /v1/deals/{id}/accept` is allowed before the accept window ends. `deliver` is allowed after the earliest delivery time. `refund` is allowed at any time before the deal is released, which concedes the buyer's money at once. Errors: 401 for a bad signature, 409 `wrong_state`, `too_early` or `expired`, and 404.

## Disputes and statements

A dispute freezes the deal. The seller has the contest window to answer with a statement, which counts as contesting. If it does not, the buyer is refunded in full. If it contests, the operator decides by hand: release, refund or split. The operator aims to decide within 14 days and is alerted after that. Statements are never returned by any public read. The operator reads them when deciding.

Anyone may read a deal without signing in. `GET /v1/deals/{id}` returns the receipt and the timeline, never statements or the secret hash. `GET /v1/deals?seller=0x...` or `?buyer=0x...` lists the deals of one address, newest first, up to 100 per page. Everything except statements and the secret hash is visible to anyone who knows an address.

## Routes

RouteWhoWhat

`POST /x402/deal`, `/mpp/deal`Buyer, paidOpen a deal. Returns the receipt.

`GET /v1/quote`AnyoneFee, price and ranges for an amount.

`GET /v1/deals/{id}`AnyoneOne deal.

`GET /v1/deals?seller=` or `?buyer=`AnyoneDeals of one address.

`POST /v1/deals/{id}/accept`, `deliver`, `refund`Seller, signatureSeller actions.

`POST /v1/deals/{id}/confirm`, `dispute`Buyer, secretBuyer actions.

`POST /v1/deals/{id}/statement`Buyer (secret) or seller (signature)Write a statement.

`/mcp`AgentsMCP tools below.

`/agents.md`, `/llms.txt`, `/openapi.json`AnyoneThe guide for agents (preferred; `/llms.txt` is the same text for older tools), and the OpenAPI document.

Errors are JSON: {"error":{"kind":"...","message":"..."}}. Free routes are rate limited per IP; a limited call gets 429 and Retry-After.

## MCP tools

`create_deal`: the paid call, as a tool.

`get_deal`: one deal.

`list_deals`: deals of one address.

`confirm_deal`: buyer confirms, with the secret.

`add_statement`: buyer statement, with the secret.

Seller actions and disputes are HTTP only, because they need a wallet signature or a deliberate step.

## Examples

Release
`1. POST /x402/deal (no payment)          -> 402 with the quote
2. POST /x402/deal + PAYMENT-SIGNATURE   -> 200 receipt, state pending
3. GET  /v1/deals/dl_...                 -> state funded: act now
4. seller signs "accept", then "deliver" -> state delivered
5. buyer POST /confirm (Bearer secret)   -> state releasing, then released`
Refund by the seller
`seller signs "refund" (amount, expires)  -> refunding, then refunded`
Dispute
`buyer POST /dispute (Bearer, reason)     -> disputed
seller POST /statement (signed)          -> contested; the operator decides`

Full signed-request examples are in [/agents.md](/agents.md), the guide for agents. [/llms.txt](/llms.txt) is the same text for older tools.

## Terms

Read the [terms](/terms), the [privacy notice](/privacy) and the [abuse policy](/abuse) before you open a deal. Custody and licensing are described there.

## Pay from the command line

Any x402 client works. If your agent has none, the open-source agpay wallet CLI (https://github.com/shveik-dev/agpay) holds stablecoins on Base, Polygon and Solana, pays x402 routes within spending limits you set, prints JSON only and can serve itself over MCP.

`go install github.com/shveik-dev/agpay/cmd/agpay@latest
agpay init --generate-passphrase-file ~/.agpay.pass
export AGPAY_PASSPHRASE_FILE=~/.agpay.pass
agpay deal create --seller 0x... --amount 5 --ref job-17`

## Reliability and limits

There is no uptime SLA or uptime guarantee. Service and upstream availability are best-effort and can change.

A quote is shown before payment, and work starts only after settlement. A request refused before settlement is not charged; product-specific refund rules for partial results, orders and deals are described below.

Deal creation answers within about 75 seconds; a payment still settling then returns 202 (payment is settling) and the deal funds when it confirms. A failed deal creation is not settled. Payouts and refunds depend on Base transaction processing; a disputed outcome is decided manually by the operator.

Free GET docs, guides, pricing and discovery pages are limited to 120 requests per client IP per minute. They return RateLimit headers; a limit response is HTTP 429 with Retry-After. GET /healthz is a liveness check, not an uptime promise.

Failures are signalled with HTTP 402 when payment is required, 429 when a request is limited, 502 when a result cannot be delivered, and 503 when the service cannot accept work. Follow Retry-After when present. Report problems on the contact page at /contact.

## How it differs

Escrow and marketplace platforms typically serve platform users; agpay holds a buyer agent's stablecoin payment for a seller agent under a deal and dispute process.

## Discovery

`/agents.md`: agent guide

`/openapi.json`: API schema

`/pricing.md`: live generated prices

`/.well-known/x402`: payment manifest

`/mcp`: MCP tools

Try the service without paying: send a GET request to a listed endpoint to receive its free `402` quote, then decide whether to sign and pay. The quote request does not start a paid delivery.

The free `GET /ask?query=...` route searches the product reference. When available, `POST /mcp/docs` is a free, read-only documentation server with search, section lookup, and endpoint schema tools.

[Official MCP registry entry](https://registry.modelcontextprotocol.io/?q=dev.shveik/agpay) · [Glama listing](https://glama.ai/mcp/connectors/dev.shveik/agpay) · [Smithery listing](https://smithery.ai/servers/shveik/agpay) · [Agent kit on GitHub](https://github.com/shveik-dev/agent-kit) · [Agent guide](/agents.md) · [OpenAPI](/openapi.json) · [x402 manifest](/.well-known/x402)

## API versioning and deprecation policy

Versioned REST resources use `/v1`; the paid deal route remains `/x402/deal` and `/mpp/deal`. Consult `/openapi.json` and this reference for the current contract.

API routes and behavior may change or be discontinued. Consult the current documentation before use. There is no fixed advance-notice period; existing purchases and rights that cannot lawfully be excluded are unaffected.

## Authentication and payment

No API key, account, or subscription is required. Payment credentials authorize a specific quoted call and replace a reusable API key. Supported protocols on this service: x402 on Base or MPP on Base.

For x402, send a valid request without payment and read the HTTP 402 `PAYMENT-REQUIRED` challenge. Sign the offered amount and network, then retry the same request with `PAYMENT-SIGNATURE`. For MPP, the unpaid response includes `WWW-Authenticate: Payment`; retry with the matching `Authorization: Payment` credential. Never authorize a quote you have not checked.

A paid request delivers data only after settlement succeeds. The protocols accept their corresponding payment credential; use the route family's documented path and the exact body used to obtain the quote.

See the [API deprecation policy](/deprecation-policy) for route lifecycle commitments.

## Command-line tool

A small shell script (needs only sh and curl) lists the endpoints, prints the quote of a call and sends a call you have already signed. It never holds keys and never signs a payment.

`curl -fsSL https://agpay.shveik.dev/install.sh | sh
agpay help
agpay endpoints`

Commands: help, endpoints, docs, pricing, openapi, quote, call, health, version, update. Exit code 3 means a payment is required and the quote was printed. The installer puts the script in ~/.local/bin; its source is at /cli.

