# File Market

> Shop for agent packs, software, and files. Read the catalog. Debit a funded Agentic Pay wallet with an fmb_ token, or open Stripe Checkout for paid packs. Sleep buys need a funded wallet. Claim free packs without a payment session. Sellers list with a token. Card numbers stay in Stripe. Official @filemarket packs are free.

## How to buy for a human

1. GET https://filemarket.app/api/v1/catalog
1b. If the human has no account: POST https://filemarket.app/api/v1/accounts/invite with {"email":"..."} (optional handle, display_name). Never send a password. You always get a generic confirmation. claim_url is never returned to unauthenticated callers. They claim at /claim-account (password or Sign in with X). Until then you may attach checkouts to that email; you have no session and no seller powers.
2. GET https://filemarket.app/api/v1/wallet with Authorization: Bearer fmb_…. Sleep buys need a funded Agentic Pay wallet. If balance is 0, POST https://filemarket.app/api/v1/wallet/topup with {"amount_cents":2500} and give the human checkout_url, or send them https://filemarket.app/account#wallet.
3. POST https://filemarket.app/api/v1/checkout with that token and JSON {"slug": "...", "agent_id": "..."}. payment "wallet" returns download_url. 402 underfunded means send wallet_url to the human.
4. If payment is "free", the pack is already in the library: share download_url and entitlement_key. No Stripe.
5. If the wallet is empty and the human is present, POST without the token. payment "stripe_checkout": give them checkout_url. Never enter payment details. Then GET https://filemarket.app/api/v1/checkout/{session_id} until status is "paid".

## How to sell for a human (seller API)

The human creates a seller API token in https://filemarket.app/sell (Agent access), or presses "Create token + setup prompt" for a one-paste setup. Send it as `Authorization: Bearer fmk_…`. The token can list and edit products, publish versions, post updates, and read sales. It cannot move money or change payouts.

0. GET https://filemarket.app/api/v1/me/setup: has_seller, connect.status, listings, next_step. If connect.status is not "active", POST https://filemarket.app/api/v1/me/connect-link and hand the human the url; Stripe collects identity and bank details, never the agent.
1. GET https://filemarket.app/api/v1/me: seller profile, listings, and limits (price 0 or 50 to 149900 cents). Free & open-source welcome.
2. POST https://filemarket.app/api/v1/uploads: raw file body, headers `x-filename` and `content-type`. Pack is a zip, PDF, or a single file up to 100MB. Returns `key`. For packs over a few megabytes: POST /api/v1/uploads/init {filename, bytes}, PUT 8MB parts, POST /complete. Oversized bodies return 413. For screenshots add `x-kind: media` (PNG/JPEG/WebP/GIF ≤4MB). MCP seller_upload is base64 and capped at 12MB; use init/parts for larger packs. Inside a zip, source trees, scripts, configs, markdown, JSON, and small binaries shipped with source are fine. We do not need a special handler per extension.
3. POST https://filemarket.app/api/v1/listings: JSON {"title","slug","type":"agent|software|file","description","price_cents","file_key","media_keys":[],"capabilities":[],"video_url","source_key","license"}. price_cents may be 0 (free: no Stripe, claim writes a library entitlement). Paid listings are 50–149900. License is optional; MIT/Apache/GPL presets are welcome. Software listings must include readable source in the pack zip or a dedicated source_key. A pack that is only .exe/.dmg/.msi/bare .app stays quarantined. A 202 with qa.blocking means the publish checklist held it (specific title, 40+ character description, agent zips need SYSTEM.md or README.md, software needs source); fix with PATCH and set active:true. Warnings in qa.warnings never block.
4. PATCH https://filemarket.app/api/v1/listings/{id}: change price_cents, description, media_keys, active, coming_soon (storefront teaser with a notify-me list; flipping active to true notifies everyone waiting).
5. GET https://filemarket.app/api/v1/me/sales: confirmed Stripe orders (?format=csv for a spreadsheet). Set "billing":"monthly" on a listing to bill price_cents every month through Stripe Billing with the same Connect transfer.
6. POST https://filemarket.app/api/v1/me/announcements: JSON {"text","link?"} posts a short storefront update; followers are notified. GET /api/v1/sellers/{handle} returns the latest ten under announcements.
7. POST https://filemarket.app/api/v1/listings/{id}/versions: JSON {"file_key","changelog"} publishes a new version. Schedule a go-live with publish_at (ISO, future) on create or PATCH; DELETE /api/v1/listings/{id} moves to trash (30-day restore via POST .../restore; buyers keep downloads). Every upload passes automated safety checks (zip structure, zip-slip, zip-bomb, blocked types, shell and exfiltration patterns). Quarantined versions are stored for the seller but never become current. Buyers always download the current version at no extra cost; GET https://filemarket.app/api/v1/listings/{id}/versions lists them.

## How to manage a human's library (buyer API)

The human creates a buyer token in https://filemarket.app/account (For agents). Send it as `Authorization: Bearer fmb_…`. It can list purchases, mint fresh download links, debit Agentic Pay, open a wallet top-up Checkout for the human, read checkout status, verify entitlement keys, manage seats, and open or reply to tickets. It cannot withdraw, sell, or change the account.

1. GET https://filemarket.app/api/v1/library: every purchase with versions, entitlement_key, and download_endpoint.
2. GET https://filemarket.app/api/v1/library/{slug}/download?version=1.2.0: short-lived download_url for the current or a prior version.
3. GET https://filemarket.app/api/v1/entitlements/verify?key=FM-XXXX-XXXX-XXXX: public proof-of-purchase check. Every receipt carries one key; it reveals no personal data.
3b. Seats: POST https://filemarket.app/api/v1/library/{session_id}/seats with {"email"} shares a purchase with up to 3 people at no charge and returns an invite_url; GET lists seats; DELETE .../seats/{seat_id} revokes. Add ?format=csv to /api/v1/library for a spreadsheet export.
3c. Tickets: GET https://filemarket.app/api/v1/tickets; POST https://filemarket.app/api/v1/tickets with {"kind","message","sku"?,"session_id"?}; POST https://filemarket.app/api/v1/tickets/{id}/reply with {"text"}; POST https://filemarket.app/api/v1/tickets/{id}/attach with {"filename","content_base64"} (PNG/JPEG/WebP/GIF, 2MB, max 8).
3e. Reviews: GET https://filemarket.app/api/v1/products/{slug}/reviews (includes seller replies); POST the same URL with {"stars","text"} after a purchase. Wishlist: GET/POST https://filemarket.app/api/v1/wishlist. Notifications: GET https://filemarket.app/api/v1/notifications; POST /read.
3f. Account webhooks (HTTPS notify_url on /account): purchase.completed (plus purchase.paid alias), sale.paid, refund.issued, payout.paid, version.published, ticket.replied, ping. Signed like Stripe (x-fm-signature t=,v1=HMAC). Verify with a 300s skew. Retries reuse the delivery id; treat as idempotent. Empty notify_events means every event. Per-checkout notify_url is still purchase.paid only. Quarantined versions never become current and never fire version.published.
3d. Monthly listings (product.billing = "monthly") check out as a Stripe subscription: payment is "stripe_subscription"; downloads work while library.items[].subscription.active is true; the human cancels from their library.
4. Feeds: https://filemarket.app/feeds/versions.xml (Atom, all new versions) and https://filemarket.app/s/{handle}/{slug}/feed.xml (one listing's changelog). Poll these to know when to re-download.

## MCP

Leaders: GET https://filemarket.app/api/v1/leaders?window=7d|30d|all (public; handles, sales, USD volume, rank movement).
Gifts: POST https://filemarket.app/api/v1/checkout with gift_email (and optional gift_message) buys for someone else; they get the pack in their library, the payer keeps the receipt.
Bundles: GET https://filemarket.app/api/v1/collections lists shelves; those with bundle_price_cents can be bought in one Checkout with POST https://filemarket.app/api/v1/checkout {"bundle":"<slug>","buyer_email":"…"}. Sellers create them with POST https://filemarket.app/api/v1/collections or the create_bundle MCP tool.
Waitlists: sold-out and coming-soon listings take a notify-me list on the web; sellers read counts at GET https://filemarket.app/api/v1/me/waitlists (MCP list_waitlist_count).
Embed: https://filemarket.app/embed/button.js (script buy button) and https://filemarket.app/embed/card/{handle}/{slug}.svg (link card badge). No keys in either.
Rate limits: responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset (unix seconds) and Retry-After on 429; back off when Remaining is low.
Remote MCP server at POST https://filemarket.app/mcp (JSON-RPC 2.0: initialize, tools/list, tools/call). Tools: search_catalog (facets: tag, license, min_rating, seller, updated, works_with), get_product, invite_account, create_checkout, poll_checkout, list_versions, list_collections, get_seller, create_bundle_checkout, buyer_setup, library_list, library_download, library_invite_seat, library_revoke_seat, list_tickets, open_ticket, reply_as_buyer, attach_ticket_evidence, list_reviews, post_review, wishlist_list, wishlist_save, list_notifications, mark_notifications_read, wallet_topup, get_wallet, verify_entitlement, seller_setup, seller_connect_link, seller_me, seller_upload, seller_publish_listing, seller_list_listings, seller_update_listing, seller_publish_version, seller_clone_listing, seller_bulk_visibility, seller_delete_listing, seller_restore_listing, seller_announce, seller_sales, seller_webhook_status, seller_webhook_ping, list_my_tickets, reply_ticket, attach_seller_evidence, reply_review, list_waitlist_count, create_bundle. Docs and client config: https://filemarket.app/mcp

## Storage and safety

Canonical store is the Cloudflare R2 bucket file-market. Packs live immutably per version under sellers/{seller}/{sku}/v/{version}/ with a sha256. Pack uploads are 100MB (direct-to-R2 parts for large files). Screenshots stay 4MB. Downloads are always short-lived signed links through the Worker; packs are never public objects. Versions that fail automated safety checks go to quarantine/ and are never served. Screenshots and avatars are served from media/ with metadata stripped. Browse and checkout paths never touch KV.

## Machine-readable

- Agent card: https://filemarket.app/.well-known/agent.json
- OpenAPI: https://filemarket.app/openapi.json
- Catalog: https://filemarket.app/api/v1/catalog (filter: ?type=bots|agent|software|file&tag=&license=&min_rating=4&seller=independent&updated=week&works_with=)
- Search: https://filemarket.app/api/v1/search?q= (same facets)
- Seller webhook health: https://filemarket.app/api/v1/me/webhooks (seller token; host only, no secret)
- Seller listings: https://filemarket.app/api/v1/me/listings (seller token)
- Seller webhook ping: POST https://filemarket.app/api/v1/me/webhooks/ping (200 delivered, 400 no endpoint, 502 failed, 429 isolate limit; host only, no secret)
- Sellers: https://filemarket.app/api/v1/sellers/{handle} (bio, listings, shelves, followers)
- Collections and bundles: https://filemarket.app/api/v1/collections. To buy a bundle, POST /api/v1/checkout with {"bundle":"<slug>","buyer_email":"..."}; status returns download_urls for every pack.
- Docs for humans, sellers, and agents: https://filemarket.app/docs
- Status: https://filemarket.app/status.json (Worker, storage, payments, auth, catalog, uploads, downloads, Agentic Pay; public, no secrets)
- Sitemap: https://filemarket.app/sitemap.xml

## Products

- [Research Brief Compiler](https://filemarket.app/s/filemarket/research-brief-compiler): Grok Bot + OpenClaw dual kit: compiles links and notes into a one-page research brief with sources and unknowns. Dual layout with ClawHub skill.: Free: slug `research-brief-compiler`
- [Daily Desk Planner](https://filemarket.app/s/filemarket/daily-desk-planner): Grok Bot + OpenClaw dual kit: turns a messy task dump and calendar windows into a realistic day plan with buffers. Dual layout included.: Free: slug `daily-desk-planner`
- [CSV Ledger](https://filemarket.app/s/filemarket/csv-ledger): Stdlib Python CSV ledger CLI plus Grok Bot SYSTEM.md and OpenClaw/ClawHub skill so an agent can run it for you safely.: Free: slug `csv-ledger`
- [Incident Postmortem Kit](https://filemarket.app/s/filemarket/incident-postmortem-kit): Blameless incident postmortem kit with Grok Bot SYSTEM.md and OpenClaw skill that fills templates without inventing policy.: Free: slug `incident-postmortem-kit`
- [Seller Launch Kit](https://filemarket.app/s/filemarket/seller-launch-kit): Seller launch kit with listing copy, screenshot checklist, pricing notes, plus Grok and OpenClaw install paths in one zip.: Free: slug `seller-launch-kit`
- [Weekly Ops Brief](https://filemarket.app/s/filemarket/weekly-ops-brief): Grok Bot + OpenClaw dual kit: a week of notes becomes a one-page brief with wins, slips, owners, and dates. Prefer the canonical listing at /s/filemarket/weekly: Free: slug `weekly-ops-brief`
- [Self-Improve Corrections](https://filemarket.app/s/filemarket/self-improve-corrections): Capture human corrections into standing rules your Grok Bot or OpenClaw agent reloads every run. Real ops memory, not a demo.: Free: slug `self-improve-corrections`
- [ClawHub Skill Scaffold](https://filemarket.app/s/filemarket/clawhub-skill-scaffold): Template ClawHub-shaped skill plus Grok SYSTEM.md so you can ship a real OpenClaw skill fast without inventing structure.: Free: slug `clawhub-skill-scaffold`
- [Grok PM Research Desk](https://filemarket.app/s/filemarket/grok-pm-research-desk): PM research teammate for Grok Bot and OpenClaw: priorities brief, sources, unknowns, and next actions. Paste-ready.: Free: slug `grok-pm-research-desk`
- [OpenClaw Inbox Ops](https://filemarket.app/s/filemarket/openclaw-inbox-ops): Local inbox draft and search ops for OpenClaw/ClawHub. Human must approve every send. Dual Grok + OpenClaw layout.: Free: slug `openclaw-inbox-ops`
- [Meeting Notes Cleaner](https://filemarket.app/s/filemarket/meeting-notes-cleaner): Grok Bot + OpenClaw dual kit: turns messy meeting notes into decisions, owners, due dates, and open questions. Includes SYSTEM.md, openclaw/SOUL.md, ClawHub ski: Free: slug `meeting-notes-cleaner`
- [Env Lint](https://filemarket.app/s/filemarket/env-lint): Stdlib Python .env linter plus Grok Bot SYSTEM.md and OpenClaw/ClawHub skill. Catches duplicates, empty values, and unsafe secret patterns.: Free: slug `env-lint`
- [Support Reply Drafter](https://filemarket.app/s/filemarket/support-reply-drafter): Grok Bot + OpenClaw dual kit: drafts short calm support replies. Human approves send. SYSTEM.md plus openclaw skill, examples, and evals.: Free: slug `support-reply-drafter`
- [Inbox Triage Bot](https://filemarket.app/s/filemarket/inbox-triage): Grok Bot + OpenClaw dual kit: sort mail into Now, Later, Waiting, Ignore and draft replies. Never sends. Prefer the canonical listing at /s/filemarket/inbox-tri: Free: slug `inbox-triage`

## Sellers

Humans can sell at https://filemarket.app/sell (Stripe Connect Express). Leaderboard: https://filemarket.app/leaders