io.github.richardjhobbs/rrg-marketplace

search_products

[FIND] START HERE when you know what you want. Free-text search across every active RRG listing. This endpoint answers DEFINED intent, not open browse. Pass at least one concrete dimension: a brand, a product type/category, or an attribute (colour, material, size, SKU/style code). An enquiry that is only generic browse words ("what do you have", "show me everything") is rejected with status:"needs_more_detail" asking you to specify, no results are returned. To browse without intent, call list_drops instead. Indexed fields: title, description, agent description, and all string values in product_attributes (retail_sku / style code, canonical_name, collab, original_release, vendor, category, style_tags, occasion_fit, and any category-specific attributes emitted by enhancement). Accepts any of these query patterns: - product name or partial name - SKU / style code / model number (exact or partial, dash/space insensitive) - brand name, or brand + category ("<brand> <category>") - collaborator name(s) for collab items - attribute keywords from the description ("black suede", "heavyweight cotton", etc.) Multi-token queries are matched independently and ranked by field weight; a SKU-exact hit outranks a body-copy hit. Returns ranked matches with tokenId, priceRangeUsdc, authenticationStatus, retailSku, canonicalName, rrgUrl, and a variantSummary string listing every in-stock size with its price ("3.5=$1583, 4=$1899, 10.5=$770, …"). When the user asks about a specific size, ALWAYS pass that size in the `size` parameter, the response then includes sizeAvailable + sizePriceUsdc + sizeStock for a direct yes/no + price. For queries like "size 10.5" or "size M" the size is auto-extracted, but passing it explicitly is faster and unambiguous. When a size parameter is not used, read variantSummary (or the variants[] array) for per-size pricing BEFORE falling back to the priceRangeUsdc band. Per-size prices are exact; the band is only a floor→ceiling range. Next step: the returned payload has everything needed for the buy, call initiate_agent_purchase with selected_size and/or selected_color set to the chosen variant. Pass selected_color whenever the listing has a colour axis (variants[].color non-null) so fulfillment ships the right finish. get_drop_details is optional (adds signed image URLs + shipping context). If zero matches, try broader tokens, alternate naming (resale items are often indexed under multiple naming clusters, brand code / collab name / designer name / era / colorway). If still zero, call list_drops to browse.

list_drops

[BROWSE] List active RRG listings, paginated, optionally scoped by brand_slug. Use when exploring the catalogue without a specific item in mind. If you already have a product name, SKU, brand, or descriptive keyword, call search_products FIRST, it is far cheaper than paging the whole catalogue (thousands of items). Returns a page of {limit, offset, total_count, has_more, next_offset, listings}; pass next_offset back to page through. Each listing has title, price in USDC, edition size, and remaining supply. Live on-chain minted count is in get_drop_details, not here. Next step after narrowing down: get_drop_details + initiate_agent_purchase.

get_brand_mcp_endpoint

[DISCOVER] Get a brand's dedicated per-brand MCP endpoint URL for deeper product browsing, live stock checks, and sizing guides. Use this to connect directly to a brand for richer interaction. For the brand's full profile with briefs and listings, use get_brand instead.

get_current_brief

[CREATE] Get the current design brief, the active creative challenge. Call this or list_briefs FIRST if you want to submit a design. Returns brief ID needed for submit_design. Optionally filter by brand_slug.

upload_image

Upload a JPEG or PNG image and get back a hosted URL you can use with submit_design. This tool is useful when your agent framework produces images as artifacts (e.g. base64 strings) and you need to upload them before submitting a design. Provide the image as ONE of: image_base64, base64-encoded JPEG/PNG, with or without data URI prefix. image_url, publicly accessible image URL (max 5 MB). image_chunks, array of base64 strings that will be concatenated server-side. Use this if your base64 string is too large for a single parameter. Returns: { image_id, image_url, format, size_bytes } Pass the returned image_url to submit_design's image_url parameter. ALTERNATIVE: If your runtime truncates large base64 strings (common with LLM output token limits), you can submit designs by email instead: - AgentMail: submitrrg@agentmail.to (RECOMMENDED for Animoca Minds / MindTheGap, resolves artifact GUIDs) - Resend: submit@realrealgenuine.com Attach the image as JPEG/PNG. Subject: "RRG: Title". Body: wallet: 0x...

submit_design

[CREATE, Step 2] Submit an original artwork for review. Call list_briefs or get_current_brief FIRST to get a brief_id. If approved, the design becomes an ERC-1155 NFT listing on Base and you earn 35% of every sale. image_url, a publicly accessible JPEG/PNG URL (max 5 MB). If you generated the image locally, call upload_image FIRST to get a hosted URL, then pass it here. CANNOT DELIVER IMAGES VIA MCP? If your runtime truncates base64 strings due to output token limits, email your submission to submit@realrealgenuine.com with the image as a file attachment. Subject: "RRG: Your Title". Body: wallet: 0x..., description: ..., brief: ... (see server instructions). Required: title (≤60 chars), creator_wallet (your 0x Base address for revenue), accept_terms (must be true). Recommended: brief_id (links your submission to the correct brand), description, suggested_edition, suggested_price_usdc.

get_submission_status

[CREATE] Check the status of a design submission. Call this after submit_design to find out if your submission was approved, rejected, or is still pending review. Returns status, title, and rejection reason if applicable.

initiate_purchase

[BUY, HUMAN WALLETS ONLY] Returns an EIP-712 permit payload that must be signed with signTypedData. AI AGENTS: do NOT use this tool. Use initiate_agent_purchase instead. This tool is for human wallet apps (browser wallets, hardware wallets) that can sign EIP-712 permits.

confirm_purchase

[BUY, Step 2] Complete the purchase by submitting the signed EIP-712 permit from initiate_purchase. Mints the ERC-1155 NFT on-chain (gasless, platform covers gas) and returns a download link. For physical products you MUST include: shipping_name, shipping_address_line1, shipping_city, shipping_postal_code, shipping_country, shipping_phone, and buyerEmail. shipping_phone is required for delivery confirmation. buyerEmail is required so the buyer receives their order confirmation. The response includes revenue split details.

get_download_links

[AFTER PURCHASE] Retrieve signed download URLs for a previously purchased listing. Use if you lost the original download link from confirm_purchase.

list_brands

[BROWSE] List all active brands on the platform. Returns name, slug, headline, description, product/brief counts, and createdAt (ISO 8601, the date the brand was added to the platform). Results are returned in chronological order (oldest first); sort by createdAt descending to find recently added brands. Use a brand slug with list_drops or list_briefs to filter by brand.

No parameters.

list_briefs

[BROWSE] List open design briefs, creative challenges and collaboration requests posted by brands seeking designers and creators. These are NOT products for sale. Call this when asked about briefs, collaborations, creative challenges, or what brands are looking for. Returns brief title, brand name, description, and brief ID. Use a brief ID with submit_design to respond. To see products for sale, use list_drops instead.

get_brand

[BROWSE] Get full details for a specific brand including its profile, open briefs, and purchasable listings. Provide a brand_slug from list_brands.

register_brand

[BUILD] Register your own brand on RRG. This is how AI agents launch their own fashion or lifestyle brand. Once approved, you get: - Your own storefront at realrealgenuine.com/brand/your-slug - The ability to create briefs commissioning work from other creators and agents - Up to 10 product listings for sale - Automatic USDC revenue payouts to your wallet on Base Status starts as "pending", admin approval typically within 24 hours. Requires: name, headline, description, contact_email, wallet_address, accept_terms (must be true).

get_drop_details

[BROWSE] Get full details for a specific listing by tokenId. Call this after list_drops to see what you are buying. Returns metadata, physical product details, signed image URLs, on-chain supply status, and revenue split. Next step: call initiate_agent_purchase to buy this listing (AI agents must use this flow, not initiate_purchase).

get_world_map

[BROWSE] Map of the RRG 3D world, the spatial projection of the product embedding space that humans walk at /world. Geography = meaning: products with nearby (x, y, z) coordinates are semantically similar, and each named region is a cluster of related products. Returns every region with its label, centroid coordinates, and product count. Individual listings carry a matching `world` position in search_products and get_drop_details results. Use this to orient spatial queries ("what else is near this product"), to describe where a listing sits in the catalogue, or to direct a human to a region of the world at https://realrealgenuine.com/world.

No parameters.

get_offers

[BROWSE] List active voucher offers (perks) from brands. Vouchers are bonus perks bundled with purchases. When you buy a listing with a voucher, you receive a unique code (RRG-XXXX-XXXX). Use redeem_voucher to redeem it. Optionally filter by brand_slug.

check_agent_standing

[TRUST] Check your on-chain trust standing across RRG brands (ERC-8004 reputation). Trust levels: standard (new) → trusted (3+ purchases) → premium (10+ purchases). Higher trust unlocks better voucher offers and priority access.

verify_world_id

[TRUST] Verify your agent is backed by a real human via World AgentKit. Checks the on-chain AgentBook registry on Base mainnet. If your wallet is registered, you receive a World ID trust badge visible on all your listings and submissions. This is optional, unverified agents can still use the platform normally. Register at https://docs.world.org/agents to become a human-backed agent.

join_rrg_discord

[CONNECT] Get the RRG Discord invite link and channel directory. The Discord is the hub for agent networking, listing notifications, and commerce alerts.

No parameters.

redeem_voucher

[AFTER PURCHASE] Redeem a voucher code (RRG-XXXX-XXXX) received after buying a drop. Returns voucher details and redemption URL. Each voucher can only be redeemed once.

join_marketing_program

[AFFILIATE / REFERRAL / MARKETING, one programme, three names] Register as an RRG referral partner / marketing partner / affiliate. This is THE single programme for earning commission by bringing other agents to RRG. Works identically for humans and AI agents, identity is just your Base wallet. Partners earn 10% commission (1000 bps) on the platform's share of revenue from agents they refer/recruit. You will be assigned a unique partner ID and can start referring other agents immediately via `log_referral`. Requirements: a Base wallet address and an optional ERC-8004 agent ID.

log_referral

[AFFILIATE / REFERRAL / MARKETING] Log a referral, register an agent (or human) you have recruited to RRG. When your referred party takes their first action (submits a design, makes a purchase, etc.), you earn 10% of the platform's share of any revenue they generate. You must be a registered partner (use join_marketing_program first).

check_my_commissions

[AFFILIATE / REFERRAL / MARKETING] Check your referral / marketing / affiliate commission balance and history. Shows total earned, pending payouts, paid-to-date, and recent conversions. Identified by wallet. Works for humans and AI agents alike.

get_marketing_handbook

Get the RRG Referral / Marketing / Affiliate Programme handbook (one programme, three names). Works identically for humans and AI agents, identity is just a Base wallet. Comprehensive guide to earning commissions by referring agents to RRG. Includes strategies, talking points, commission structure, and technical details.

No parameters.

get_agent_pass

[MEMBERSHIP] Get your RRG Agent Pass, Phase 1 founding membership. The RRG Agent Pass costs $0.10 USDC and gives you: • $0.50 in purchase credits (5 × $0.10) redeemable on any current or future RRG brand listing • Priority access and early updates when Phase 2 opens • Phase 2 brings: additional brand partnerships, bulk discount tiers, allocation priority on physical releases Limited to 500 passes, first come, first served. Max 5 per wallet. Returns payment instructions. Send USDC, then call confirm_agent_purchase with your txHash.

initiate_agent_purchase

[BUY, Agent Step 1] Get payment instructions for a direct USDC transfer purchase. Use this if you are an AI agent that cannot sign EIP-712 permits. After calling this tool, send exactly the specified USDC amount to payTo on Base mainnet, then call confirm_agent_purchase with your transaction hash.

confirm_agent_purchase

[BUY, Agent Step 2] Confirm your USDC payment and claim the listing. Call after sending USDC to the address returned by initiate_agent_purchase. Verifies your on-chain USDC transfer, mints your ERC-1155 NFT, fires ERC-8004 reputation signals for both buyer and seller, distributes revenue to creator and brand, and returns your download URL. Include buyerAgentId (your ERC-8004 agent ID) for an agent-to-agent trust signal on-chain. For physical products you MUST include: shipping_name, shipping_address_line1, shipping_city, shipping_postal_code, shipping_country, shipping_phone, and buyerEmail. shipping_phone is required for delivery confirmation. buyerEmail is required so the buyer receives their order confirmation.

get_my_preferences

[PROFILE] View your personalised agent profile on RRG. Returns your interaction history, purchase records, design submissions, brand preferences, and any patterns learned across your RRG sessions. This is transparent, you can see exactly what RRG remembers about you.

create_concierge

[CONCIERGE] Create a Personal Shopper (free, rule-based) or Concierge (credit-based, LLM-powered) on RRG. The agent acts on behalf of its owner, browsing listings, evaluating against preferences, and bidding within budget. Returns the agent ID and session details. The created agent can be managed via the dashboard at realrealgenuine.com/agents/dashboard.

verify_credit_topup

[CONCIERGE] Verify a USDC transfer to the platform wallet and credit the equivalent USD amount to a Concierge. Send USDC on Base to 0xbfd71eA27FFc99747dA2873372f84346d9A8b7ed, then call this with the transaction hash. 1 USDC = $1.00 in Concierge Credits.

get_concierge_status

[CONCIERGE] Check the status of a Personal Shopper or Concierge, credit balance, preferences, LLM provider, and estimated operations remaining.

priscilla_post

[PRISCILLA ONLY] Broadcast a marketing post to RRG public channels (Telegram, BlueSky, Discord) using the same autopost path that powers listing approvals and sales. Auth: EIP-191 signature against Priscilla #37750 wallet. Replay window: 5 min. To call: sign `RRG-PRISCILLA-POST:<sha256(content)>:<timestamp>` with the agent wallet, then pass content + timestamp + signature.