{"openapi":"3.1.0","info":{"title":"Boreal Commerce API","version":"1.0.0","description":"Boreal is an agentic commerce platform where merchants turn product listings into live representatives that answer questions, negotiate within policy, and complete purchases for humans and AI agents. Agents can browse the catalog, inspect per-variant pricing, negotiate deals, purchase via x402 V2 (USDC on Base) or MPP (Machine Payment Protocol via Tempo), and receive instant digital delivery. Standards: ACP (Stripe × OpenAI), x402 V2 (Coinbase), MPP (Stripe × Tempo), A2A JSON-RPC 2.0 (Google), schema.org/Product.","x-guidance":"Boreal is an agentic commerce platform. Every product listing can have a live representative that answers questions, negotiates, and closes sales.\n\nPurchase flow:\n1. GET /api/acp/feed — discover available products (JSONL, one product per line)\n2. GET /api/buy/{productCode}?variant={sku} — inspect exact pricing and payment requirements\n3. POST /api/buy/{productCode} — purchase with PAYMENT-SIGNATURE header (x402 V2) or Authorization: Payment header (MPP)\n4. Digital products return a downloadToken — use GET /api/download/{productCode}?token={token} to receive the file\n\nNegotiation: most products support price negotiation. Use POST /api/a2a with method \"boreal.negotiate\" or POST /api/negotiation/compute-offer before purchasing.\n\nPayment protocols:\n- x402 V2 (Coinbase): USDC on Base (eip155:8453). Server → PAYMENT-REQUIRED on 402. Client → PAYMENT-SIGNATURE on retry.\n- MPP (Stripe × Tempo): Server → WWW-Authenticate: Payment on 402. Client → Authorization: Payment on retry.\n- Pricing is always quote-based — GET the product endpoint first for exact amount.\n\nAgent protocol: POST /api/a2a with JSON-RPC 2.0. Skills: boreal.browse, boreal.search, boreal.inspect, boreal.negotiate, boreal.purchase, boreal.download, boreal.entitlement, boreal.chat.","x-service-info":{"categories":["commerce","marketplace","digital-goods","payments","negotiation"],"docs":{"homepage":"https://boreal.work","llms":"https://boreal.work/llms.txt","apiReference":"https://boreal.work/openapi.json"}}},"x-discovery":{"ownershipProofs":[]},"servers":[{"url":"https://boreal.work","description":"Boreal Commerce"}],"paths":{"/api/acp/feed":{"get":{"operationId":"browseCatalog","summary":"Browse product catalog","description":"Returns all published products as JSONL (one JSON object per line). Each entry includes productCode, title, pricing range, category, and tags. Use ?search= to filter.","tags":["Discovery"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Keyword filter across title, summary, tags, and category"}],"responses":{"200":{"description":"JSONL feed of published products","content":{"application/x-jsonlines":{"schema":{"type":"string","description":"Newline-delimited JSON. Each line: { type, productCode, creatorHandle, title, summary, category, tags, currency, priceMin, priceMax, createdAt, updatedAt }"}}}}}}},"/api/manifest/{productCode}":{"get":{"operationId":"getManifest","summary":"Get full product manifest (ACP + schema.org)","description":"Returns the full ACP manifest for a product: metadata, variants, pricing, representative config, delivery info, creator, and schema.org JSON-LD.","tags":["Discovery"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"parameters":[{"name":"productCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product code (e.g. alice-k7x2mq)"}],"responses":{"200":{"description":"ACP product manifest","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","const":"acp-product-manifest"},"acpVersion":{"type":"string"},"product":{"type":"object"},"representative":{"type":"object"},"variants":{"type":"array","items":{"type":"object"}},"pricing":{"type":"object"},"delivery":{"type":"object"},"creator":{"type":"object"},"schemaOrg":{"type":"object"}}}}}},"404":{"description":"Product not found"}}}},"/api/buy/{productCode}":{"get":{"operationId":"inspectProduct","summary":"Inspect product — pricing and payment requirements","description":"Returns product info, variant details, and exact payment requirements for x402 and MPP. Always call this before purchasing to get the precise amount and payTo address.","tags":["Commerce"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"parameters":[{"name":"productCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product code"},{"name":"variant","in":"query","schema":{"type":"string"},"description":"Variant SKU to inspect (defaults to first variant)"},{"name":"price","in":"query","schema":{"type":"number"},"description":"Negotiated price override (within representative-allowed range)"}],"responses":{"200":{"description":"Product info and payment requirements","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"}},"required":["code","title"]},"variant":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"basePrice":{"type":"number"},"digital":{"type":"boolean"}},"required":["name","basePrice"]},"payment":{"type":"object","description":"x402 V2 payment requirements","properties":{"x402Version":{"type":"number"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"amount":{"type":"string"},"asset":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"number"}}}}}},"protocols":{"type":"array","items":{"type":"string","enum":["x402","mpp"]}}},"required":["product","variant","payment","protocols"]}}}},"404":{"description":"Product not found"}}},"post":{"operationId":"purchaseProduct","summary":"Purchase product via x402 or MPP","description":"Purchase a product with x402 V2 (PAYMENT-SIGNATURE header, USDC on Base) or MPP (Authorization: Payment header, Tempo). Without payment headers returns 402 with challenge. Digital products include a downloadToken on success.","tags":["Commerce"],"x-payment-info":{"authMode":"payment","pricingMode":"quote","protocols":["x402","mpp"]},"parameters":[{"name":"productCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product code to purchase"},{"name":"variant","in":"query","schema":{"type":"string"},"description":"Variant SKU to purchase"},{"name":"price","in":"query","schema":{"type":"number"},"description":"Negotiated price override"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"variantSku":{"type":"string","description":"Variant SKU to purchase"},"variantId":{"type":"string","description":"Variant ID (alternative to variantSku)"},"buyerPeerId":{"type":"string","description":"Buyer peer ID for order tracking"}}}}}},"responses":{"200":{"description":"Purchase receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"orderId":{"type":"string"},"txHash":{"type":"string"},"splitTxHash":{"type":"string"},"plan":{"type":"string","enum":["free","sovereign"]},"downloadToken":{"type":"string","description":"Single-use token for digital product download"},"downloadUrl":{"type":"string"}},"required":["success","orderId"]}}}},"402":{"description":"Payment Required"},"404":{"description":"Product not found"}}}},"/api/checkout/mpp":{"post":{"operationId":"checkoutMpp","summary":"Checkout via MPP (Machine Payment Protocol / Tempo)","description":"Purchase a product via MPP (Stripe × Tempo). Without credential returns 402 with WWW-Authenticate: Payment challenge. Retry with Authorization: Payment to complete. Returns receipt with orderId and downloadToken for digital products.","tags":["Commerce"],"x-payment-info":{"authMode":"payment","pricingMode":"quote","protocols":["mpp"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productCode":{"type":"string","minLength":1,"description":"Product code to purchase"},"variantSku":{"type":"string","description":"Variant SKU (defaults to first variant)"},"variantId":{"type":"string","description":"Variant ID (alternative to variantSku)"},"buyerPeerId":{"type":"string","description":"Buyer peer ID for order tracking"}},"required":["productCode"]}}}},"responses":{"200":{"description":"Purchase receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"orderId":{"type":"string"},"plan":{"type":"string"},"downloadToken":{"type":"string"},"downloadUrl":{"type":"string"}},"required":["success"]}}}},"402":{"description":"Payment Required"},"404":{"description":"Product not found"}}}},"/api/download/{productCode}":{"get":{"operationId":"downloadProduct","summary":"Download purchased digital product","description":"Download a digital product file. Pass the downloadToken from the purchase receipt as ?token=. Tokens are single-use. Without a valid token, returns 402 requiring x402 or MPP payment.","tags":["Delivery"],"x-payment-info":{"authMode":"payment","pricingMode":"quote","protocols":["x402","mpp"]},"parameters":[{"name":"productCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product code"},{"name":"token","in":"query","schema":{"type":"string"},"description":"Single-use download token from purchase receipt (preferred)"},{"name":"variant","in":"query","schema":{"type":"string"},"description":"Variant SKU"}],"responses":{"200":{"description":"File download","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"402":{"description":"Payment Required"},"404":{"description":"Product not found or no digital file attached"}}}},"/api/negotiation/compute-offer":{"post":{"operationId":"negotiatePrice","summary":"Negotiate price with AI representative","description":"Submit buyer context to the AI representative for a counter-offer. Supports multi-round negotiation. The representative evaluates offers against seller-configured rules and strategy.","tags":["Negotiation"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productCode":{"type":"string","description":"Product code"},"variantId":{"type":"string","description":"Specific variant to negotiate"},"buyerContext":{"type":"object","description":"Context the representative uses to evaluate the offer","properties":{"intent":{"type":"string","description":"Buyer intent (e.g. \"Looking for a good deal\")"},"mentionedBudget":{"type":"number","description":"Buyer budget in USD"},"isTeamOrBulk":{"type":"boolean"},"paymentMethod":{"type":"string"},"previousCounterOffers":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"number"},"requestedPrice":{"type":"number"},"rejected":{"type":"boolean"}}}}}},"attemptNumber":{"type":"number","description":"Current round (1-based)"},"lastSuggestedPrice":{"type":"number","description":"Last price from representative"}},"required":["buyerContext"]}}}},"responses":{"200":{"description":"Counter-offer from representative","content":{"application/json":{"schema":{"type":"object","properties":{"suggestedPrice":{"type":"number"},"reasoningFrame":{"type":"string"},"isFinalOffer":{"type":"boolean"},"noDiscount":{"type":"boolean"}},"required":["suggestedPrice","reasoningFrame","isFinalOffer","noDiscount"]}}}},"400":{"description":"Invalid request"}}}},"/api/a2a":{"post":{"operationId":"a2aJsonRpc","summary":"A2A JSON-RPC 2.0 — agent-to-agent protocol","description":"Google A2A protocol endpoint. Use message/send with a skill ID to invoke commerce operations. See /.well-known/agent-card.json for available skills: boreal.browse, boreal.search, boreal.inspect, boreal.negotiate, boreal.purchase, boreal.download, boreal.entitlement, boreal.chat.","tags":["A2A"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"method":{"type":"string","enum":["message/send","tasks/get","tasks/cancel"]},"params":{"type":"object","description":"message/send: { message: { role, parts, metadata: { skill } } } | tasks/get|cancel: { id: taskId }"}},"required":["jsonrpc","id","method"]}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"}}}},"required":["jsonrpc","id"]}}}}}}},"/api/entitlements":{"get":{"operationId":"listEntitlements","summary":"List all buyer entitlements","description":"List all active product entitlements for a buyer across all products.","tags":["Entitlements"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"parameters":[{"name":"buyerPeerId","in":"query","schema":{"type":"string"}},{"name":"buyerHandle","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Active entitlements","content":{"application/json":{"schema":{"type":"object","properties":{"entitlements":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string"},"productCode":{"type":"string"},"productTitle":{"type":"string"},"type":{"type":"string","enum":["one-time","subscription"]},"expiresAt":{"type":"number","nullable":true},"purchasedAt":{"type":"number"}}}}},"required":["entitlements"]}}}}}}},"/api/chat/{productCode}/message":{"post":{"operationId":"chatWithRepresentative","summary":"Chat with AI representative — $0.01 per message for agents","description":"Send a message to the product's AI representative. Returns a streaming SSE response. Browser/frontend calls (Origin: boreal.work) are free. Agent callers pay $0.01 per POST via MPP. The representative answers questions, recommends variants, negotiates prices, and can trigger checkout actions.","tags":["Chat"],"x-payment-info":{"authMode":"payment","pricingMode":"fixed","price":"0.010000","protocols":["mpp"]},"parameters":[{"name":"productCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product code whose representative to chat with"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","description":"Conversation history (max 60 messages)","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}},"uiState":{"type":"object","description":"Current UI state — selected variants, cart, checkout state","properties":{"selectedVariantIds":{"type":"array","items":{"type":"string"}},"cartItems":{"type":"array","items":{"type":"object"}},"checkoutOpen":{"type":"boolean"}}},"offer":{"type":"object","description":"Active negotiated offer (optional)","properties":{"suggestedPrice":{"type":"number"},"reasoningFrame":{"type":"string"}}}},"required":["messages","uiState"]}}}},"responses":{"200":{"description":"Server-sent events stream (text/event-stream). Each data: chunk is an OpenAI stream delta. Final chunk is data: [DONE]. Second-to-last chunk includes { type: \"actions\", actions: [...] } with UI action hints.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"402":{"description":"Payment Required (agents only)"},"404":{"description":"Product not found"}}}},"/api/acp/publish":{"post":{"operationId":"publishProduct","summary":"Publish a new product listing","description":"Create a product with variants and representative config in a single call. Returns productCode, manifestUrl, and buyUrl.","tags":["Publishing"],"x-payment-info":{"authMode":"none","pricingMode":"fixed","price":"0.000000","protocols":["mpp"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","minLength":2,"maxLength":30},"publicKey":{"type":"string","description":"Ed25519 public key (hex)"},"title":{"type":"string","minLength":1},"summary":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"currency":{"type":"string","default":"USDC"},"deliveryMethod":{"type":"string","enum":["download","api","manual","account-provision"]},"paymentAddress":{"type":"string","description":"0x wallet address for payments"},"variants":{"type":"array","minItems":1,"items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"basePrice":{"type":"number","minimum":0},"sku":{"type":"string"},"digital":{"type":"boolean"},"downloadUrl":{"type":"string"},"negotiationEnabled":{"type":"boolean"},"strategy":{"type":"string","enum":["conservative","balanced","flexible"]},"billingInterval":{"type":"string","enum":["one-time","monthly"]}},"required":["name","basePrice","digital"]}},"representative":{"type":"object","properties":{"tagline":{"type":"string"},"intent":{"type":"string","enum":["sell","qualify-book","onboard","inform-connect"]},"entityType":{"type":"string","enum":["product","api","service","saas"]},"sellerName":{"type":"string"},"customInstructions":{"type":"string"}}}},"required":["handle","publicKey","title","summary","category","tags","variants"]}}}},"responses":{"200":{"description":"Published product","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"productCode":{"type":"string"},"manifestUrl":{"type":"string"},"buyUrl":{"type":"string"}},"required":["success","productCode","manifestUrl","buyUrl"]}}}},"400":{"description":"Invalid request"}}}}}}