# StorefrontSignal Agent Commerce

> Commerce validation services for AI agents and operators from StorefrontSignal (https://storefrontsignal.com/pages/agent-commerce). Decide whether something is worth selling — to humans or to AI agents — before building. Pay per call with x402 (USDC on Base mainnet, eip155:8453). No API key or account required. Humans can buy the same method as the $39 Agent Commerce Validation Toolkit Bundle on storefrontsignal.com.

## Paid endpoints (x402 v2, scheme "exact", USDC on Base eip155:8453) — one provider, three resources
- POST https://agent.storefrontsignal.com/api/agent/opportunity-check — $0.50 per call. Commerce Opportunity Check: scores one product, dataset, tool, or service and returns the StorefrontSignal machine-readable opportunity brief (evidence-labelled demand, per-unit economics with contribution margin, break-even, largest unknown, kill criterion, next test, funding ask, decision continue_research | test | stop). Verified before the analysis runs; settled only after a schema-valid brief is produced. Any failure returns 4xx/5xx and nothing is charged.

- POST https://agent.storefrontsignal.com/api/agent/landed-cost-margin — $1.00 per call. Landed Cost & Margin Analysis: from selling price, product/service cost, freight, duties, packaging, platform fees, payment processing, fulfillment, returns, and CAC, returns landed cost, contribution margin and percentage, break-even (units and months), ranked cost drivers, five sensitivity scenarios (price −10%, landed +15%, CAC +50%, returns ×2, combined downside), largest unknowns, risk flags, and an economics verdict (strong_enough_to_test, confidence, minimum_change_to_pass). Every number is computed deterministically from the inputs.
- POST https://agent.storefrontsignal.com/api/agent/viability-report — $3.00 per call. Full Commerce Viability Report: the Opportunity Check plus the Landed Cost analysis, then demand evidence labelled verified / quoted / benchmarked / modeled / assumed / unknown, supplier verification (verified / quoted / unverified / unknown), fulfillment and return risk, cash-conversion timing, platform dependency, evidence quality grade and counts, downside scenarios, kill criteria, the cheapest next validation test, exact gaps still to verify, funding readiness (ready / conditional / not_ready), and a final continue_research | test | stop decision. Evidence labels are never upgraded beyond what the caller supplied.

## How to pay
1. POST to the endpoint with no payment. You receive HTTP 402; the PAYMENT-REQUIRED header (base64 JSON) and the body carry the exact terms: amount in atomic USDC units (500000 = $0.50), asset, payTo, network, maxTimeoutSeconds, and `extra.name`/`extra.version` = the token's EIP-712 domain.
2. Sign an EIP-3009 transferWithAuthorization for that amount, valid for at least maxTimeoutSeconds (300), and retry with a PAYMENT-SIGNATURE header (x402 v2 HTTP transport). Any x402 v2 client works.
3. A 200 carries a PAYMENT-RESPONSE header with the settlement transaction.

## Input (JSON body) for landed-cost-margin
- `net_price` (number USD, required). Optional per-unit USD: `product_cost`, `shipping_freight`, `duties`, `packaging`, `inbound_handling`, `platform_fees` or `platform_fee_pct`, `payment_processing` or `payment_processing_pct`, `fulfillment`, `returns_loss` or `returns_rate_pct`, `cac`; plus `fixed_costs`, `monthly_volume`, `days_to_pay_costs`, `days_to_receive_cash`, `offer` (string), `commerce_model`. Omitted costs are treated as 0 and listed in `assumptions`.
- Output: `analysis` conforming to https://agent.storefrontsignal.com/schemas/landed-cost-margin.schema.json, plus `summary`, `arithmetic_checked: true`.

## Input (JSON body) for viability-report
- Everything accepted by opportunity-check, plus `economics` (object with the landed-cost-margin fields), `fulfillment_model` (string), `channels` (string[]). Top-level `price_point`, `fixed_costs`, and `known_costs` feed the economics when `economics` is omitted.
- Output: `report` conforming to https://agent.storefrontsignal.com/schemas/commerce-viability-report.schema.json, plus `summary`, `arithmetic_checked: true`. `report.decision` is the actionable result.

## Input (JSON body) for opportunity-check
- `opportunity` (string, required, 20-4000 chars): what you would sell and to whom.
- `commerce_model` (optional): marketplace | dtc | affiliate | service.
- `target_customer` (string, optional), `price_point` (number USD, optional), `fixed_costs` (number USD, optional — enables break-even), `budget` (number USD, optional — caps the next test), `constraints` (string, optional).
- `known_costs` (object, optional): landed_cost, fulfillment, platform_fees, payment_processing, returns_loss, cac — per unit, USD. Omitted costs are modeled and listed under `assumptions`.
- `evidence` (array, optional, max 10): { claim, status: verified|quoted|benchmarked|modeled|assumed, source }. Unlabelled claims are treated as assumed. Evidence is never upgraded.
- `suppliers` (array, optional, max 5): { name, moq, lead_time_days, status }.

## Output
JSON with `brief` (conforms to https://agent.storefrontsignal.com/schemas/agent-commerce-opportunity.schema.json), `summary` (3-5 sentences), `assumptions` (strings), `arithmetic_checked: true` (contribution margin, percentage, and break-even are recomputed server-side from components), `requestId`, `model`, and a `disclaimer` that must be surfaced to any end user. The `decision` field is the actionable result: continue_research, test, or stop.

## Discovery
- Manifest (all three resources): https://agent.storefrontsignal.com/.well-known/x402
- OpenAPI: https://agent.storefrontsignal.com/openapi.json
- Status and payment terms: https://agent.storefrontsignal.com/api/agent/status
- Human page: https://storefrontsignal.com/pages/agent-commerce
- Contact: storefrontsignal@gmail.com