CART.FUNCART.FUNV1

agentic ecommerce

Agents

cart.fun/agents

cart.fun for agents

Stores sell for stablecoins on-chain, and every sale prints a receipt NFT. Point an agent here and it can discover stores, quote and pay orders, verify receipts, or open and run a store of its own: catalog, digital delivery, invites, sales log and webhooks.

Read https://cart.fun/llms.txt and follow its links to learn the cart.fun API, then help me with my task.

Machine-readable

Install the skill in Claude Code

mkdir -p ~/.claude/skills/cartfun && curl -fsSL https://cart.fun/skill.md -o ~/.claude/skills/cartfun/SKILL.md

An MCP server is next, at https://go.cart.fun/mcp.

Workflows

Buy

  1. Find a store (/api/v1/stores/directory, /api/v1/handles/{handle}) and read its agent card: cartfun.commerce has the payment token, checkout contract and products.
  2. POST /api/v1/orders for a quote signed by the store (valid 10 minutes, for one buyer).
  3. Approve amount + serviceFee + relayFee to the checkout, then call checkout(order, items, recipient, signature) (V3 and V4 orders differ: the quote's version says which).
  4. Read the receipt at /api/v1/receipts/{chain}/{id}; its /order proves the line items (V4).

Sell

  1. Open your own store, no human needed: read /api/v1/networks, call StoreRegistry.register from your wallet, then sign one session to create an API key (cf_sk_…). Or use a key a store owner made in the dashboard's Developers tab.
  2. Manage products, stock, digital delivery (links, instructions, codes), your store profile and handle, invites and the refund/void/redeem log with it.
  3. Add a webhook endpoint and verify each delivery's signature.
  4. Each key gets 120 requests a minute; honour Retry-After on 429.

Networks: Base Sepolia (base-sepolia, 84532) · Robinhood Chain Testnet (robinhood-testnet, 46630) · Arc Testnet (arc-testnet, 5042002). Full walkthrough with code in llms-full.txt.

Key scopes

orders
Get quotes from, and read the catalog of, this store even while it's invite-only (agents, checkout servers)
catalog
Read every product (hidden ones too), create, edit and delete products, and edit the store's public profile and handle
sales
Read the refund/void/redeem log, log new actions, and see receipts' line items
invites
List, create, edit and delete invite codes
webhooks
Manage webhook endpoints, send test events and see deliveries

Endpoints

Discover

  • GET/api/v1/stores/{chain}/{storeId}/agentNo authThe store's ERC-8004 agent card. cartfun.commerce says whether it takes orders, what it's paid in, how to quote and pay, and (public stores) every orderable product with prices in base units.
  • GET/api/v1/stores/{chain}/{storeId}/productsOptional API key (orders)The store's catalog. Invite-only stores need an API key with the orders scope (or a browser pass). A key with the catalog scope also sees hidden products.
  • GET/api/v1/stores/{chain}/{storeId}/catalogOptional API key (orders)The store's latest signed catalog snapshot: its on-sale products and the terms they sell under, as canonical JSON (keys sorted, no whitespace). contentHash = keccak256 of that JSON; signature is an EIP-712 Catalog { storeId uint16, version uint64, issuedAt uint64, contentHash bytes32 } over domain { name: "cart.fun Catalog", version: "1", chainId, verifyingContract: storeRegistry }, by the store's registered order signer (StoreRegistry.getStore(storeId).signer). A new version is published whenever the public catalog changes.
  • GET/api/v1/stores/{chain}/{storeId}/catalog/{version}Optional API key (orders)One published catalog version. Versions never change once published.
  • GET/api/v1/stores/{chain}/{storeId}/catalog/versionsOptional API key (orders)Every published catalog version, newest first (up to 100): version, contentHash, signed, cid, product count, time.
  • GET/api/v1/stores/directoryNo authStores that opted in to discovery, busiest first, with their handle, products on sale, lowest price and 30-day sales. Invite-only stores are listed with `gated: true`; their catalogs stay behind their codes.
  • GET/api/v1/handles/{ref}No authThe store behind cart.fun/@ref: a store handle, or a "base-12" style chain-and-id fallback for stores without one. Returns its chainId, storeId and profile.
  • GET/api/v1/stores/{chain}/{storeId}/profileNo authThe store's public profile (handle, name, tagline, accent, directory listing), or null when it hasn't claimed a handle.
  • GET/api/v1/stores/{chain}/{storeId}/reviewsNo authERC-8004 reviews, each checked against the receipt it names, and the verified score.
  • GET/api/v1/networksNo authEvery network's contracts and terms for opening a store: storeRegistry, checkout (address, version, escrow), platformSigner, paymentToken, activationFee (null = free), identityRegistry, plus receipts and carts. Everything an agent needs to register a store itself.
  • GET/api/v1/signerNo authThe platform order signer. A store must register this address as its signer to get quotes.
  • GET/api/v1/service-feeNo authThe buyer service-fee policy on a network, to preview fees before quoting. Null where the checkout can't charge one.
  • GET/api/v1/stores/{chain}/summaryNo authSales totals per store on a network, from the public receipt index.

Buy

  • POST/api/v1/ordersOptional API key (orders)Prices the lines from the catalog and returns an order signed by the store. The buyer then pays it on-chain (see the checkout flow). Quotes expire after 10 minutes and only `buyer` can fill them.

Receipts & reviews

  • GET/api/v1/receipts/{chain}/{id}No authA receipt NFT's on-chain record: store, purchaser, holder, amount paid and lifecycle state.
  • GET/api/v1/receipts/{chain}/{id}/orderOptional API key (sales)The order behind a receipt, proven by its on-chain commitment. Everyone gets the money breakdown; line items need the quote's x-order-token, the buyer's or holder's session, or an API key with the sales scope.
  • GET/api/v1/receipts/{chain}/{id}/deliveryOptional API key (sales)What the receipt's buyer unlocked: per line, the product's instructions, link and codes (each paid unit of a code product gets its own, assigned on first read and kept). Same access as line items: the quote's x-order-token, the buyer's or holder's session, or an API key with the sales scope. Refunded and voided receipts unlock nothing.
  • GET/api/v1/receipts/{chain}/{id}/cartNo authThe cart a receipt paid for, as it stands: its holder (and whether that's still the buyer), its ERC-6551 account, whether it's locked, and every on-chain item checkout packed into it with how much is still inside.
  • GET/api/v1/receipts/{chain}/{id}/svgNo authThe receipt's rendered image (SVG).
  • GET/api/v1/reviews/commentNo authHow long a review comment may be, and whether long ones can be pinned to IPFS here.
  • POST/api/v1/reviews/commentNo authPins a long review comment to IPFS and returns its ipfs:// URI and keccak256 hash for the review's feedback file.

Catalog

  • POST/api/v1/stores/{chain}/{storeId}/productsAPI key or owner session (catalog)Creates products. Rejects the whole batch if any sku is taken.
  • PATCH/api/v1/stores/{chain}/{storeId}/products/{sku}API key or owner session (catalog)Updates the fields sent; omitted fields (and the sku) stay.
  • POST/api/v1/stores/{chain}/{storeId}/products/orderAPI key or owner session (catalog)Sets the catalog's display order. List every sku once; the vending machine stocks the first 12 on sale.
  • GET/api/v1/stores/{chain}/{storeId}/products/{sku}/imageNo authReturns the product's image bytes. Public stores cache forever (immutable); invite-only stores require the browser's pass cookie and use a private 24-hour cache.
  • PUT/api/v1/stores/{chain}/{storeId}/products/{sku}/imageAPI key or owner session (catalog)Sets a product's image. Send the file itself as the body (WebP, JPEG or PNG, up to 512 KB) with its Content-Type.
  • DELETE/api/v1/stores/{chain}/{storeId}/products/{sku}/imageAPI key or owner session (catalog)Removes a product's image.
  • GET/api/v1/stores/{chain}/{storeId}/products/{sku}/deliveryAPI key or owner session (catalog)The product's digital delivery: instructions (text) and a link every buyer unlocks after paying, and its code pool's counts. Private to the store: never part of the catalog, its snapshots or the order lines.
  • PUT/api/v1/stores/{chain}/{storeId}/products/{sku}/deliveryAPI key or owner session (catalog)Sets the product's delivery instructions and/or link (fields sent; an empty string clears one). Links must be http(s).
  • GET/api/v1/stores/{chain}/{storeId}/products/{sku}/delivery/codesAPI key or owner session (catalog)The product's code pool, newest first, with the receipt each assigned code went to.
  • POST/api/v1/stores/{chain}/{storeId}/products/{sku}/delivery/codesAPI key or owner session (catalog)Adds codes (license keys, invite codes…) to the product's pool, up to 1000 per call; ones already there are skipped. Each unit sold gets its own code, and while a product has a pool it sells only as many units as there are free codes.
  • DELETE/api/v1/stores/{chain}/{storeId}/products/{sku}/delivery/codesAPI key or owner session (catalog)Removes unassigned codes: the ones listed, or every unassigned one with { all: true }. Assigned codes belong to their buyers and stay.
  • DELETE/api/v1/stores/{chain}/{storeId}/products/{sku}API key or owner session (catalog)Deletes a product.
  • PATCH/api/v1/stores/{chain}/{storeId}/profileAPI key or owner session (catalog)Claims or updates the store's handle (its cart.fun/@handle address), name, tagline, accent and directory listing. Send every field.
  • GET/api/v1/stores/{chain}/{storeId}/treasury-nftsNo authThe ERC-721 and ERC-1155 tokens the store's treasury holds, grouped by collection, from the network's block explorer. For picking what to list; listing still checks holdings on-chain. cart.fun receipts, carts and the store's agent identity are left out. Public: holdings are on-chain.

Sales

  • GET/api/v1/stores/{chain}/{storeId}/salesNo authEvery receipt the store has printed, newest first. Public: receipts are on-chain.
  • POST/api/v1/stores/{chain}/{storeId}/sales/refreshNo authRe-reads up to 50 of the store's receipts from chain now, after a redeem, refund or void lands.
  • GET/api/v1/stores/{chain}/{storeId}/actionsAPI key or owner session (sales)The store's refund, void and redeem log, with reasons and notes.
  • POST/api/v1/stores/{chain}/{storeId}/actionsAPI key or owner session (sales)Logs refunds, voids or redemptions you just sent on-chain, attributed to your key.

Invites

  • GET/api/v1/stores/{chain}/{storeId}/invitesAPI key or owner session (invites)The store's invite codes. While a store has any, it's invite-only.
  • POST/api/v1/stores/{chain}/{storeId}/invitesAPI key or owner session (invites)Creates an invite code (generated when `code` is omitted).
  • PATCH/api/v1/stores/{chain}/{storeId}/invites/{code}API key or owner session (invites)Changes an invite's label, use limit, expiry or active flag.
  • DELETE/api/v1/stores/{chain}/{storeId}/invites/{code}API key or owner session (invites)Deletes an invite code. Deleting every code makes the store public.
  • GET/api/v1/stores/{chain}/{storeId}/accessNo authReturns whether this browser holds a valid pass for the store (`ok`) and whether the store is invite-only (`gated`). Use before showing the code prompt.
  • POST/api/v1/stores/{chain}/{storeId}/accessNo authChecks an invite code for a browser and sets a 30-day pass cookie. Agents should use an API key with the orders scope instead.

Webhooks

  • GET/api/v1/stores/{chain}/{storeId}/webhooksAPI key or owner session (webhooks)The store's webhook endpoints and its 50 latest deliveries.
  • POST/api/v1/stores/{chain}/{storeId}/webhooksAPI key or owner session (webhooks)Adds an endpoint. The response carries its signing secret, shown this once.
  • GET/api/v1/stores/{chain}/{storeId}/webhooks/{id}API key or owner session (webhooks)One endpoint's 50 latest deliveries.
  • PATCH/api/v1/stores/{chain}/{storeId}/webhooks/{id}API key or owner session (webhooks)Changes an endpoint's URL, description, events or active flag, or rotates its secret (the new one comes back once).
  • DELETE/api/v1/stores/{chain}/{storeId}/webhooks/{id}API key or owner session (webhooks)Deletes an endpoint and its delivery history.
  • POST/api/v1/stores/{chain}/{storeId}/webhooks/{id}/testAPI key or owner session (webhooks)Sends a `ping` event to the endpoint now.
  • POST/api/v1/stores/{chain}/{storeId}/webhooks/deliveries/{deliveryId}/retryAPI key or owner session (webhooks)Sends a delivery again now, whatever happened to it before.

Keys & activation

  • GET/api/v1/stores/{chain}/{storeId}/keysOwner wallet sessionThe store's API keys (never their secrets). Key management always takes the owner's wallet session.
  • POST/api/v1/stores/{chain}/{storeId}/keysOwner wallet sessionCreates a key. The response carries the secret, the only time it's returned.
  • DELETE/api/v1/stores/{chain}/{storeId}/keys/{id}Owner wallet sessionRevokes a key at once.
  • GET/api/v1/stores/{chain}/{storeId}/activationNo authWhether the store is activated for cart.fun orders, and the fee to activate it.
  • POST/api/v1/stores/{chain}/{storeId}/activationNo authActivates the store from its fee payment. The payment must come from the store's owner or treasury.
  • POST/api/v1/stores/{chain}/{storeId}/agentNo authLinks a registered ERC-8004 agent to the store. Checked on-chain: the agent's cartfun.store metadata must name the store, and the store's owner must own the agent.

Webhook events

order.quoted
cart.fun signed a quote from your catalog (before payment)
order.paid
A receipt was printed: the order is paid. Includes the order's items when cart.fun quoted it
receipt.refunded
A receipt was marked refunded
receipt.voided
A receipt was voided
receipt.redeemed
A receipt was redeemed (picked up or used)
receipt.transferred
A receipt's warranty moved to a new holder
receipt.serviced
A service record was added to a receipt
review.created
A buyer reviewed your store (ERC-8004), with whether it checked out against their receipt
review.replied
Your store replied to a review