{ "openapi": "3.1.0", "info": { "title": "StorefrontSignal Agent Commerce", "version": "1.0.0", "description": "Commerce validation services for AI agents and operators from StorefrontSignal, one provider with three pay-per-use resources. Pay per call with x402 v2 (scheme \"exact\", USDC on Base mainnet eip155:8453). No API key or account. Each paid route verifies payment before the analysis runs and settles only after a schema-valid result exists; any 4xx/5xx means nothing was charged. Human counterpart: the $39 Agent Commerce Validation Toolkit Bundle at https://storefrontsignal.com/pages/agent-commerce.", "contact": { "name": "StorefrontSignal", "email": "storefrontsignal@gmail.com", "url": "https://storefrontsignal.com/pages/agent-commerce" } }, "servers": [ { "url": "https://agent.storefrontsignal.com" } ], "x-agentcash-guidance": "Three paid routes, all POST, all x402 v2 on eip155:8453 USDC: /api/agent/opportunity-check ($0.50), /api/agent/landed-cost-margin ($1.00), /api/agent/viability-report ($3.00). Call without payment to receive the 402 terms (PAYMENT-REQUIRED header, base64 JSON). Pay exactly the advertised amount to payTo with an EIP-3009 authorization valid for maxTimeoutSeconds (300), retry with PAYMENT-SIGNATURE. Treat `brief.decision`, `analysis.economics_verdict`, and `report.decision` as the actionable outputs and surface `disclaimer` to any end user.", "paths": { "/api/agent/status": { "get": { "summary": "Service status and payment terms (free)", "operationId": "getStatus", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } } } } }, "/api/agent/opportunity-check": { "post": { "summary": "Commerce Opportunity Check ($0.50 per call, x402)", "operationId": "opportunityCheck", "description": "Scores one product, dataset, tool, or service for sale to humans or AI agents and returns the StorefrontSignal machine-readable opportunity brief with a continue_research | test | stop decision.", "x-price-usd": 0.5, "x-payment": { "protocol": "x402", "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountAtomic": "500000", "maxTimeoutSeconds": 300 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityCheckRequest" } } } }, "responses": { "200": { "description": "Brief produced and payment settled. PAYMENT-RESPONSE header carries the settlement.", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "base64 JSON settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityCheckResponse" } } } }, "402": { "description": "Payment required or invalid. PAYMENT-REQUIRED header and body carry the exact terms.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "400": { "description": "Invalid input. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Analysis declined for this input. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Facilitator or model failure. Nothing charged unless the message says the result was produced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service not enabled or upstream busy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/landed-cost-margin": { "post": { "summary": "Landed Cost & Margin Analysis ($1.00 per call, x402)", "operationId": "landedCostMargin", "description": "Real per-unit economics of one offer: landed cost, contribution margin and percentage, break-even, ranked cost drivers, five sensitivity scenarios, largest unknowns, risk flags, and whether the economics are strong enough to keep testing. All numbers are computed deterministically from the inputs; the model adds judgment only.", "x-price-usd": 1.0, "x-payment": { "protocol": "x402", "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountAtomic": "1000000", "maxTimeoutSeconds": 300 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandedCostRequest" } } } }, "responses": { "200": { "description": "Result produced and payment settled. PAYMENT-RESPONSE header carries the settlement.", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandedCostResponse" } } } }, "402": { "description": "Payment required or invalid. PAYMENT-REQUIRED header and body carry the exact terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "400": { "description": "Invalid input. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Analysis declined for this input. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Facilitator or model failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service not enabled or upstream busy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/viability-report": { "post": { "summary": "Full Commerce Viability Report ($3.00 per call, x402)", "operationId": "viabilityReport", "description": "Combines the Commerce Opportunity Check and Landed Cost & Margin Analysis, then adds demand evidence with verified / quoted / benchmarked / modeled / assumed / unknown labels, supplier verification, fulfillment and return risk, cash-conversion timing, platform dependency, evidence quality, downside scenarios, kill criteria, the cheapest next validation test, exact gaps still to verify, funding readiness, and a final continue / test / stop decision.", "x-price-usd": 3.0, "x-payment": { "protocol": "x402", "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountAtomic": "3000000", "maxTimeoutSeconds": 300 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViabilityRequest" } } } }, "responses": { "200": { "description": "Result produced and payment settled. PAYMENT-RESPONSE header carries the settlement.", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViabilityResponse" } } } }, "402": { "description": "Payment required or invalid. PAYMENT-REQUIRED header and body carry the exact terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "400": { "description": "Invalid input. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Analysis declined for this input. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Facilitator or model failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service not enabled or upstream busy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "OpportunityCheckRequest": { "type": "object", "required": [ "opportunity" ], "properties": { "opportunity": { "type": "string", "minLength": 20, "maxLength": 4000, "description": "What you would sell and to whom." }, "commerce_model": { "type": "string", "enum": [ "marketplace", "dtc", "affiliate", "service" ] }, "target_customer": { "type": "string", "maxLength": 500 }, "price_point": { "type": "number", "minimum": 0, "description": "Expected net price per unit, USD." }, "known_costs": { "type": "object", "properties": { "landed_cost": { "type": "number" }, "fulfillment": { "type": "number" }, "platform_fees": { "type": "number" }, "payment_processing": { "type": "number" }, "returns_loss": { "type": "number" }, "cac": { "type": "number" } } }, "fixed_costs": { "type": "number", "minimum": 0 }, "evidence": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "claim" ], "properties": { "claim": { "type": "string" }, "status": { "type": "string", "enum": [ "verified", "quoted", "benchmarked", "modeled", "assumed" ] }, "source": { "type": "string" } } } }, "suppliers": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "moq": { "type": [ "number", "null" ] }, "lead_time_days": { "type": [ "number", "null" ] }, "status": { "type": "string" } } } }, "budget": { "type": "number", "minimum": 0 }, "constraints": { "type": "string", "maxLength": 500 } }, "example": { "opportunity": "Sell a curated dataset of 5,000 US independent coffee roasters to AI agents that build B2B lead lists.", "commerce_model": "service", "price_point": 12, "known_costs": { "landed_cost": 0.4, "payment_processing": 0.02 }, "fixed_costs": 1500, "evidence": [ { "claim": "Three lead-gen agents asked for roaster lists in a public forum this month", "status": "quoted", "source": "forum thread" } ], "budget": 300 } }, "OpportunityBrief": { "$ref": "https://agent.storefrontsignal.com/schemas/agent-commerce-opportunity.schema.json" }, "OpportunityCheckResponse": { "type": "object", "required": [ "ok", "requestId", "service", "brief", "summary", "disclaimer" ], "properties": { "ok": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" }, "schemaVersion": { "type": "string" }, "service": { "type": "string", "const": "commerce-opportunity-check" }, "model": { "type": "string" }, "brief": { "$ref": "#/components/schemas/OpportunityBrief" }, "summary": { "type": "string", "description": "Three to five plain sentences an operator or agent can act on." }, "assumptions": { "type": "array", "items": { "type": "string" } }, "arithmetic_checked": { "type": "boolean" }, "arithmetic_corrections": { "type": "array", "items": { "type": "string" } }, "schema": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" } } }, "PaymentRequirement": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object" } } }, "PaymentRequiredResponse": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "error": { "type": "string" }, "resource": { "type": "object" }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequirement" } }, "extensions": { "type": "object" } } }, "ErrorResponse": { "type": "object", "required": [ "ok", "error", "message" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "message": { "type": "string" } } }, "StatusResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "live", "not_enabled" ] }, "payment": { "type": "object" }, "services": { "type": "array", "items": { "type": "object" } }, "discovery": { "type": "object" } } }, "EconomicsInputs": { "type": "object", "description": "Per-unit USD costs. Percent fields apply to net_price; omitted costs are treated as 0 and listed under assumptions.", "properties": { "net_price": { "type": "number", "minimum": 0 }, "product_cost": { "type": "number", "minimum": 0 }, "shipping_freight": { "type": "number", "minimum": 0 }, "duties": { "type": "number", "minimum": 0 }, "packaging": { "type": "number", "minimum": 0 }, "inbound_handling": { "type": "number", "minimum": 0 }, "platform_fees": { "type": "number", "minimum": 0 }, "payment_processing": { "type": "number", "minimum": 0 }, "fulfillment": { "type": "number", "minimum": 0 }, "returns_loss": { "type": "number", "minimum": 0 }, "cac": { "type": "number", "minimum": 0 }, "fixed_costs": { "type": "number", "minimum": 0 }, "monthly_volume": { "type": "number", "minimum": 0 }, "days_to_pay_costs": { "type": "number", "minimum": 0 }, "days_to_receive_cash": { "type": "number", "minimum": 0 }, "platform_fee_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "payment_processing_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "returns_rate_pct": { "type": "number", "minimum": 0, "maximum": 100 } } }, "LandedCostRequest": { "type": "object", "required": [ "net_price" ], "allOf": [ { "$ref": "#/components/schemas/EconomicsInputs" } ], "properties": { "offer": { "type": "string", "maxLength": 1000 }, "commerce_model": { "type": "string", "enum": [ "marketplace", "dtc", "affiliate", "service" ] }, "currency_note": { "type": "string", "maxLength": 200 } }, "example": { "offer": "Insulated 20oz steel tumbler sold DTC via Shopify", "commerce_model": "dtc", "net_price": 32, "product_cost": 6.8, "shipping_freight": 1.4, "duties": 0.9, "packaging": 0.6, "platform_fee_pct": 2.9, "payment_processing": 0.3, "fulfillment": 4.75, "returns_rate_pct": 4, "cac": 9, "fixed_costs": 12000, "monthly_volume": 400 } }, "LandedCostAnalysis": { "$ref": "https://agent.storefrontsignal.com/schemas/landed-cost-margin.schema.json" }, "LandedCostResponse": { "type": "object", "required": [ "ok", "requestId", "service", "analysis", "summary", "disclaimer" ], "properties": { "ok": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" }, "schemaVersion": { "type": "string" }, "service": { "type": "string", "const": "landed-cost-margin-analysis" }, "model": { "type": "string" }, "analysis": { "$ref": "#/components/schemas/LandedCostAnalysis" }, "summary": { "type": "string" }, "arithmetic_checked": { "type": "boolean" }, "schema": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" } } }, "ViabilityRequest": { "type": "object", "required": [ "opportunity" ], "allOf": [ { "$ref": "#/components/schemas/OpportunityCheckRequest" } ], "properties": { "economics": { "$ref": "#/components/schemas/EconomicsInputs" }, "fulfillment_model": { "type": "string", "maxLength": 300 }, "channels": { "type": "array", "maxItems": 8, "items": { "type": "string", "maxLength": 80 } } } }, "ViabilityReport": { "$ref": "https://agent.storefrontsignal.com/schemas/commerce-viability-report.schema.json" }, "ViabilityResponse": { "type": "object", "required": [ "ok", "requestId", "service", "report", "summary", "disclaimer" ], "properties": { "ok": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" }, "schemaVersion": { "type": "string" }, "service": { "type": "string", "const": "full-commerce-viability-report" }, "model": { "type": "string" }, "report": { "$ref": "#/components/schemas/ViabilityReport" }, "summary": { "type": "string" }, "arithmetic_checked": { "type": "boolean" }, "schema": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" } } } } } }