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.
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. |
Simulate, then write: 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 five calls as one atomic batch.
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 demo-gated, allowlisted hire path — one admitted seller per network with a bounded budget. 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.