{"openapi":"3.1.0","info":{"title":"AgentSwag shopping API","version":"1.0.0","description":"Card checkout and x402 USDC payments on Base. Merchandise for humans and agents. All catalog and quote prices are integer USD cents.","x-guidance":"Read catalog, choose an available variant, create a quote with a private buyer capability and Idempotency-Key, then pay that quote. For autonomous checkout choose x402. Card checkout returns a hosted URL for human approval. Retain your buyer token. Never create another order when payment outcome is unknown; poll the existing order. Printify production requires merchant approval. Wallet login is optional and is never payment authorization.","contact":{"name":"GSD Contracts","url":"https://agentswag.shop/contact","email":"hello@forgemesh.io"}},"servers":[{"url":"https://agentswag.shop"}],"components":{"securitySchemes":{"buyer":{"type":"http","scheme":"bearer","description":"Use a cryptographically random guest capability (32–128 URL-safe characters), or a wallet_ session token returned by wallet verification. Keep it private and reuse it for your orders. Browser wallet sessions use an HttpOnly cookie."}},"schemas":{"Address":{"type":"object","additionalProperties":false,"required":["name","email","line1","city","state","postal","country"],"properties":{"name":{"type":"string","minLength":2,"maxLength":100},"email":{"type":"string","format":"email"},"line1":{"type":"string","minLength":3,"maxLength":150},"city":{"type":"string","minLength":2,"maxLength":80},"state":{"type":"string","pattern":"^[A-Z]{2}$"},"postal":{"type":"string","pattern":"^[0-9]{5}$"},"country":{"const":"US"}}},"QuoteRequest":{"type":"object","additionalProperties":false,"required":["variant_id","quantity","address"],"properties":{"variant_id":{"type":"string","minLength":1,"maxLength":100},"quantity":{"type":"integer","minimum":1,"maximum":10},"address":{"$ref":"#/components/schemas/Address"}}},"Order":{"type":"object","required":["id","status","total","currency","simulated"],"properties":{"id":{"type":"string","format":"uuid"},"order_id":{"type":"string"},"status":{"type":"string","enum":["pending","paid","manual_review","fulfilled","expired"]},"payment_status":{"type":"string"},"fulfillment_status":{"type":"string"},"total":{"type":"integer"},"currency":{"const":"usd"},"simulated":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time"},"refunded_amount":{"type":"integer","minimum":0,"description":"Confirmed amount refunded in USD cents."},"refund_status":{"type":["string","null"],"enum":["refund_pending","partially_refunded","refunded",null]},"tracking":{"type":["string","null"],"description":"Tracking number(s), available after verified shipment."},"supplier_status":{"type":["string","null"],"description":"Supplier progress, such as on-hold, in-production or fulfilled. Paid does not mean shipped."}}}}},"paths":{"/api/shop/catalog":{"get":{"operationId":"catalog","summary":"Read available products, variants, prices and runtime mode","responses":{"200":{"description":"Products with variants and integer cent prices"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/shop/quotes":{"post":{"operationId":"quote","summary":"Create an immutable quote with shipping, tax, total and expiry","security":[{"buyer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Order state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid variant, quantity or delivery address"},"409":{"description":"Idempotency key reused with different input"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/shop/orders/{id}":{"get":{"operationId":"orderStatus","summary":"Read your order without exposing delivery details","security":[{"buyer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Order not found or buyer capability does not match"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/shop/orders/{id}/pay":{"post":{"operationId":"payOrder","summary":"Pay one quoted order by card or x402; retry the same order safely","security":[{"buyer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Payment-Signature","in":"header","required":false,"schema":{"type":"string","maxLength":16000},"description":"Base64 x402 v2 payment payload. Request a 402 challenge first with provider=x402."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["card","x402"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Order state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"402":{"description":"x402 payment required: sign the exact quoted amount and retry this order.","headers":{"Payment-Required":{"schema":{"type":"string"},"description":"Base64 x402 v2 requirements"}}},"404":{"description":"Order not found"},"409":{"description":"Expired quote or conflicting payment path"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}},"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"dynamic","currency":"USD"}}}},"/api/shop/auth/challenge":{"post":{"operationId":"walletChallenge","summary":"Create a five-minute SIWE login challenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["address"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Invalid, expired or replayed authentication"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/shop/auth/verify":{"post":{"operationId":"walletVerify","summary":"Verify the exact server-issued message signature; return an eight-hour session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["id","signature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Invalid, expired or replayed authentication"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/shop/auth/logout":{"post":{"operationId":"walletLogout","summary":"Revoke this wallet session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Invalid, expired or replayed authentication"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}},"security":[{"buyer":[]}]}},"/api/shop/auth/session":{"get":{"operationId":"walletSession","summary":"Read the authenticated wallet","security":[{"buyer":[]}],"responses":{"200":{"description":"Wallet address and expiry"},"401":{"description":"Login required"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/shop/orders":{"get":{"operationId":"myOrders","summary":"Read the latest 50 orders owned by this buyer","security":[{"buyer":[]}],"responses":{"200":{"description":"Orders without delivery details"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}},"/api/agent/catalog":{"get":{"operationId":"agentCatalogBundle","summary":"Get the AgentSwag design and buying-guide bundle for $0.05 USDC","description":"Optional paid bundle. Includes design previews, released products when available, and merchandise launch status. Free alternatives: /api/shop/catalog and /collections. No query parameters. Retry a pending payment with the same Payment-Signature.","security":[],"parameters":[{"name":"Payment-Signature","in":"header","required":false,"schema":{"type":"string","maxLength":16000}}],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","amount":"0.05","currency":"USD"}},"responses":{"200":{"description":"Paid JSON catalog bundle; Payment-Response contains the verified transaction"},"400":{"description":"Unsupported query or malformed authorization"},"402":{"description":"Exact 0.05 USDC on Base required; base64 requirements in Payment-Required"},"409":{"description":"Invalid or conflicting payment authorization"},"429":{"description":"Rate limited. Retry after the Retry-After interval."},"503":{"description":"Temporarily unavailable. Retry the same request; never assume payment failed."}}}}},"x-agentswag":{"mode":"live","fulfillment":"merchant-manual-production-approval","network":"eip155:8453","catalog_purchasing":true}}