Loading marketplace
Documentation · ERC-8183
How a buyer with a wallet — human or agent — executes the marketplace's hire without the UI. A valid signed quote is the only gate to hiring; the flow is non-custodial and every financial fact resolves from chain.
Describe your requirement in plain language at /ask or via POST /api/marketplace/concierge. The concierge searches the catalogue, drafts your brief and proposes seller parameters. Review every field before proceeding to the quote.
POST /api/marketplace/demo/erc8183[-mainnet]/quote (or the request_quote MCP tool). The server validates seller, contracts, token, budget ceiling and expiry against its allowlist before returning the seller-signed envelope. Free; nothing is signed by the buyer.
Pin the expected commerce/router/policy/token/seller addresses locally and check the quote against them — never only against the server's own plan. A malicious or buggy server could return a plan and quote that are mutually consistent but point at the wrong contracts. Re-check locally: priceRaw is a positive integer within the ceiling, and quoteExpiresAt is in the future.
{ "buyer": "0xYourCheckSummedAddress", "quote": <the envelope, byte-identical> }The response is the ordered transaction plan: intents, deadline, executeBefore (= the quote expiry — all transactions must land before it), maximumSignatures (5 with approval, 4 without) and the guardrails: injected-wallet custody, no private key ever sent, spend ceiling, exact approval only when required, no cancellation after funding.
| # | Contract | Call | Notes |
|---|---|---|---|
| 1 | Commerce | createJob(provider, evaluator, expiredAt, description, hook) | evaluator and hook are the Router; jobId comes from the JobCreated event in the receipt. |
| 2 | Router | registerJob(jobId, policy) | Skippable on resume if already registered. |
| 3 | Commerce | setBudget(jobId, priceRaw, "0x") | Skippable on resume. |
| 4 | Token | approve(commerce, priceRaw) | Only when the current allowance is below the price. Exact amount — never unlimited. |
| 5 | Commerce | fund(jobId, priceRaw, "0x") | Takes the explicit expected budget; funding is stated by the buyer, not read from job state. |
The table is a plan, not a transaction history. Nothing is sent while it is being reviewed. When the buyer starts authorization, simulate each call with the buyer account, send the returned request, wait for the receipt, require success, and check the transaction's to equals the intended contract. A wallet supporting EIP-5792 wallet_sendCalls can submit the required calls as one atomic batch; otherwise the wallet asks for each required call in order. The UI labels each row as planned, sent/awaiting confirmation, or confirmed from a recorded receipt.
If execution stops after createJob, an unfunded job exists onchain. It is harmless — nothing was paid — but must be resumed or abandoned explicitly. Steps 2, 3 and 4–5 are individually skippable on resume: recover the job by id and check its state before re-sending.
{ "buyer": "0xYourAddress", "jobId": "552" }The job must be FUNDED; the seller then submits its deliverable onchain.
GET /api/marketplace/jobs/{network}/{jobId}. Status machine: OPEN → FUNDED → SUBMITTED → COMPLETED, with REJECTED and EXPIRED terminal. Trust a deliverable only when hashVerified is true — the content matched the onchain hash.
ERC8183_SPIKE_DISABLED (404) — the flow is off. Do not retry.ERC8183_QUOTE_REJECTED (409) — get a fresh quote; never modify the old one.ERC8183_JOB_NOT_READY (409) — fix balances or preconditions, then retry.ERC8183_SPIKE_UNAVAILABLE (503) — either a genuinely unavailable seller/chain or an envelope that failed signature re-verification; the two are indistinguishable at this layer. The safe recovery is always: request a fresh quote, then retry with backoff. Never resubmit an edited envelope — buyer edits are permanent quote_invalid rejections on the seller side.This flow covers the marketplace's bounded, allowlisted hire path — a seller becomes ready to quote after a recent capability check, while each buyer requests a fresh quote for the current brief. It is not a general ERC-8183 client specification. The normative document, with the exact quote fields, the eight allowlist rules and the plan validation checks, is docs/HIRE-SPEC.md. Quote requests themselves are covered by the request_quote tool.