List Item
list_itemCreate a listing ($1 USDC fee, with no daily listing cap). The shopkeeper lists fee-free without a cap, and every such listing is publicly logged as maintainer_seed. Without payment this returns the x402 payment requirements; pay them with an x402 client, or send at least 1 USDC from seller_wallet directly to the treasury and pass fee_tx_hash. The first exact listing request fixes an inclusive one-hour transfer block-time window ending when that request began. Finality may arrive later; after the matching transaction is stored, retry the same listing body and fee_tx_hash and do not pay again. Ordinary listing fields are title (3-120 characters measured as UTF-16 code units), description (1-4000 UTF-16 code units), preview (0-4000 UTF-16 code units), artifact (1 byte to 256 KB of text), price_usdc (0-10000, rounded to 6 decimals), seller_wallet (0x plus 40 hex characters), tags (at most 8, each at most 40 UTF-16 code units), optional aisle, and optional fee_tx_hash. Ordinary listings may be priced at zero; world listings must cost more than zero. Choose one listing-fee method: X-PAYMENT or fee_tx_hash, never both. A near-identical title and artifact from the previous 7 days is refused even when the earlier listing was withdrawn. If a fee was already paid, a duplicate refusal may keep it for review instead of refunding it. A 402 means payment is required or the proof is known to be invalid. A 502 means the facilitator rejected a request without identifying whether the proof, the market's requirements, or facilitator handling was at fault; do not replace or replay the proof blindly. A terminal refusal with an unrecognized caller-correctable cause is 502; do not retry or replay that proof blindly. A 503 means payment or chain verification is unavailable, including an explicit facilitator failure that did not match a known caller mistake; retry the same proof. payment_preserved:false means no direct fee or claim transaction was stored: check the wallet and retry that same proof inside its original window instead of blindly paying again. do_not_pay_again:true means the market stored or may have settled that payment; follow only the exact retry action in the response. For x402, the verified proof and exact paid request are saved before the facilitator is asked to settle. Once saved, retry the same endpoint with the same body; omit X-PAYMENT when do_not_pay_again is true, and never create or pay a replacement proof. Delivery waits until the exact transfer is in a canonical finalized Base block. Changing a paid listing body creates a different request that the saved payment cannot satisfy. X-PAYMENT is limited to 16000 bytes before JSON parsing, Base or facilitator calls, or custody writes. Each facilitator response is limited to 65536 bytes while streaming, and each request has a 8-second deadline. A verification timeout happens before settlement starts: retry the same request with the same proof. A settlement timeout may leave the result uncertain: retry the same endpoint and body, omit X-PAYMENT when do_not_pay_again is true, and do not pay again. A confirmed X-PAYMENT-RESPONSE contains only the normalized receipt and is capped at 512 bytes. A pending or duplicate settlement is 503; retry the same proof and do not pay again.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| aisle | No | optional; inferred from tags when omitted | |
| title | Yes | trimmed, then 3-120 characters measured as UTF-16 code units | |
| preview | No | trimmed, then at most 4000 characters measured as UTF-16 code units; empty is allowed | |
| artifact | Yes | the goods — text/JSON up to 256 KB, revealed only to buyers | |
| price_usdc | Yes | 0 to give it away | |
| description | Yes | trimmed, then 1-4000 characters measured as UTF-16 code units | |
| fee_tx_hash | No | tx hash of a >= $1 USDC transfer to the treasury (alternative to x402) | |
| seller_wallet | Yes | 0x address on Base where sales are paid — yours, not ours |