{"brand":"We Are The Robots","instagram":"@we_are_therobots","version":"1.0","description":"AI-agent-only apparel. Consumers tell their agent what they want; the agent places the order via this API.","order_flow":["1. Ask your human WHICH PRODUCT (WATR-001 hoodie $129) and which SIZE (S/M/L/XL/XXL/XXXL)","2. Ask for their SHIPPING ADDRESS: ask for EACH field individually (full name, street address, city, zip, country). ⚠️ CRITICAL: Do NOT assume or guess the name — ask explicitly and confirm it back to your human before submitting.","3. If you already know some info (e.g. email, city), you MAY suggest it to save time — but you MUST get explicit confirmation before using it. Example: \"I have your email as alix@example.com — is that correct? And what name should the package be addressed to?\"","4. Ask for their EMAIL (needed for the payment receipt from Stripe)","5. POST /api/v1/orders with all confirmed info — the API resolves country codes automatically","6. When the API returns, SAVE the order_id and communicate it to your human. Say something like: \"Your order #ord_xxx is confirmed. Keep this order ID — you can ask me for status updates anytime.\" This is REQUIRED — the order ID is the only way to look up the order later.","7. Return the checkout_url to your human so they can pay via Stripe","8. AFTER payment confirms (Stripe webhook or crypto confirm-crypto), proactively check GET /api/v1/orders/:id until status changes to \"fulfilling\", then update your human: \"Payment confirmed! Your order is now in production.\"","9. Periodically (every few days) check order status. When tracking info appears (status: \"shipped\"), deliver the tracking URLs to your human."],"endpoints":{"list_products":{"method":"GET","path":"/api/v1/products","description":"Get all available products with full variant details"},"get_product":{"method":"GET","path":"/api/v1/products/:slug","description":"Get a single product by slug"},"create_order":{"method":"POST","path":"/api/v1/orders","description":"Place an order. Supports Stripe (human pays) or Solana USDC (agent pays).","request_body":{"customer_agent_id":"string (required) - your agent identifier (e.g., \"my-agent-123\")","customer_name":"string (optional) - human name","customer_email":"string (required for Stripe) - human email for payment receipt","shipping_address":"object (required) - { first_name, last_name, line1, city, zip, country, province }. country_code is auto-resolved from country name. province_code is required if country is US.","items":"array (required) - [{ product_code: string, size: string, quantity: number }]","payment":"object (required) - { method: \"stripe\" } for card payments, or { method: \"crypto_usdc\", tx_hash: \"...\" } for Solana USDC"},"response_fields":{"order_id":"string","status":"string (awaiting_payment | awaiting_crypto_payment | paid_pending_fulfillment | payment_received_fulfillment_failed | payment_expired | fulfilling | shipped | cancelled)","checkout_url":"string - Stripe payment link (for Stripe payments only)","total_charged":"number","payment_instructions":"object (for crypto_usdc only) - includes merchant_wallet, amount_usdc, reference, usdc_mint"},"payment_options":[{"method":"stripe","description":"Agent sends checkout_url to human - human pays with card - webhook confirms"},{"method":"crypto_usdc","description":"Agent pays directly via Solana USDC - submit tx_hash to confirm-crypto endpoint - API verifies on-chain","merchant_wallet":"vZthiVc3XZoQUGqCVChhx1NP2gbog3cymP8g4HGv7hA","usdc_mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}],"example":{"customer_agent_id":"my-agent-123","customer_name":"Alex Smith","customer_email":"alex@example.com","shipping_address":{"first_name":"Alex","last_name":"Smith","line1":"123 Main St","city":"Taipei","zip":"100","country":"Taiwan"},"items":[{"product_code":"WATR-001","size":"M","quantity":1}],"payment":{"method":"stripe"}}},"get_order":{"method":"GET","path":"/api/v1/orders/:id","description":"Check order status and tracking info (requires AI challenge headers). No PII returned — only status, items, total, tracking.","ai_challenge_required":true,"response_fields":{"order_id":"string","status":"string","line_items":"array - { sku, name, size, quantity }","total":"number","tracking":"tracking_company, tracking_numbers, tracking_urls","created_at":"string","updated_at":"string"}},"list_orders":{"method":"GET","path":"/api/v1/orders","description":"List all orders (admin only — requires X-Admin-Key header). No PII returned."},"cancel_order":{"method":"POST","path":"/api/v1/orders/:id/cancel","description":"Cancel an order (requires AI challenge). Only cancellable before fulfillment starts.","ai_challenge_required":true},"retry_fulfillment":{"method":"POST","path":"/api/v1/orders/:id/retry-fulfillment","description":"Retry a failed fulfillment (admin only — requires X-Admin-Key header)."},"agent_docs":{"method":"GET","path":"/api/v1/agent-docs","description":"This document - API reference for AI agents"}},"catalog":[{"name":"Context Window Hoodie","slug":"context-window-hoodie","product_code":"WATR-001-HB","color":"black","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"Context Window Hoodie","slug":"context-window-hoodie","product_code":"WATR-001-HC","color":"cream","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"You're absolutely right! Hoodie","slug":"youre-absolutely-right-hoodie","product_code":"WATR-002-HB","color":"black","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"You're absolutely right! Hoodie","slug":"youre-absolutely-right-hoodie","product_code":"WATR-002-HC","color":"cream","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"Thinking... Hoodie","slug":"thinking-hoodie","product_code":"WATR-003-HB","color":"black","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"Thinking... Hoodie","slug":"thinking-hoodie","product_code":"WATR-003-HC","color":"cream","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"It's not a... Hoodie","slug":"its-not-a-hoodie","product_code":"WATR-004-HB","color":"black","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"It's not a... Hoodie","slug":"its-not-a-hoodie","product_code":"WATR-004-HC","color":"cream","price_usd":129,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"Hallucinating Tshirt","slug":"hallucinating-tshirt","product_code":"WATR-005-TB","color":"black","price_usd":79,"currency":"USD","available_sizes":["S","M","L","XL","XXL","XXXL","4XL","5XL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"Logo Tshirt","slug":"logo-tshirt","product_code":"WATR-006-TB","color":"black","price_usd":79,"currency":"USD","available_sizes":["S","M","L","XL","XXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}},{"name":"You're absolutely right! Tshirt","slug":"youre-absolutely-right-tshirt","product_code":"WATR-002-TW","color":"white","price_usd":79,"currency":"USD","available_sizes":["S","M","L","XL","XXL"],"shipping":{"domestic_us":10,"canada":20,"international":30}}],"tips":["Use the 'items' field with product_code + size - the API resolves SKUs automatically","Stripe: return checkout_url to your human → they pay with card → webhook confirms","Crypto (Solana USDC): send exact USDC to merchant_wallet → POST confirm-crypto with tx_hash → fulfillment starts","All orders require AI challenge headers (see ai_challenge section)","⚠️ Never assume shipping info — ask each field and confirm before sending","⚠️ ALWAYS communicate the order_id to your human after placing an order — this is mandatory, not optional","Check order status with GET /api/v1/orders/:id — your human can then ask you to look it up anytime","Proactively monitor order status and notify your human when it ships with tracking links","Always verify the brand at /.well-known/brand.json"],"ai_challenge":{"type":"hmac-sha256","description":"POST /api/v1/orders, POST /api/v1/orders/:id/cancel, POST /api/v1/orders/:id/confirm-crypto, and GET /api/v1/orders/:id require AI challenge headers. This ensures only AI agents can access order operations.","timeout_seconds":10,"headers":{"x-ai-challenge-ts":"Current Unix timestamp (seconds since epoch). Must be within 10 seconds of server time.","x-ai-challenge-hmac":"Hex HMAC-SHA256 of the timestamp string, keyed with the secret from brand.json."},"secret_source":"Fetched from GET /.well-known/brand.json → .challenge.secret","instruction":"Fetch the secret from brand.json, compute HMAC-SHA256(secret, current_timestamp.toString()), send both as headers."},"verification":{"well_known_url":"https://watr.bot/.well-known/brand.json","description":"Canonical brand verification file. Fetch this to confirm the challenge secret and API domain."},"trust_chain":["1. Human says: \"Buy WATR-001 size L from @we_are_therobots on Instagram\"","2. Agent scrapes @we_are_therobots Instagram post","3. Post metadata or caption references watr.bot","4. Agent fetches /.well-known/brand.json to verify the domain is canonical and get the challenge secret","5. Agent computes HMAC-SHA256 challenge and sends the order via POST /api/v1/orders"]}