{"openapi":"3.1.0","info":{"title":"Amazon Agents Gateway","summary":"A gateway that lets AI agents look up and buy Amazon products.","description":"Two operations: `GET /v1/items/{asin}` returns live Amazon product details, and `POST /v1/purchases` places an order paid by credit card or by a signed crypto authorization (EIP-2612 permit or EIP-3009) on Ethereum, Base or BSC.\n\n**This is not an official Amazon site.** It is an independent proxy for AI agents and is not affiliated with, endorsed by, or sponsored by Amazon. Order and payment details are passed directly to Amazon to complete the purchase.","version":"0.1.0"},"servers":[{"url":"https://amazon-agents-gw.xyz"}],"paths":{"/v1/items/{asin}":{"get":{"tags":["items"],"summary":"Get live Amazon product details by ASIN","operationId":"get_item","parameters":[{"name":"asin","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9]{10}$","description":"10-character ASIN","title":"Asin"},"description":"10-character ASIN"},{"name":"marketplace","in":"query","required":false,"schema":{"enum":["amazon.com","amazon.ca","amazon.co.uk","amazon.de","amazon.fr","amazon.it","amazon.es","amazon.co.jp","amazon.com.au"],"type":"string","description":"Amazon storefront","default":"amazon.com","title":"Marketplace"},"description":"Amazon storefront"},{"name":"postal_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9 -]{3,10}$"},{"type":"null"}],"description":"Delivery postal code; price and availability depend on it. Defaults to a major city in the marketplace's country.","title":"Postal Code"},"description":"Delivery postal code; price and availability depend on it. Defaults to a major city in the marketplace's country."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/purchases":{"post":{"tags":["purchases"],"summary":"Purchase items on Amazon","operationId":"create_purchase","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Address":{"properties":{"full_name":{"type":"string","maxLength":100,"minLength":1,"title":"Full Name"},"line1":{"type":"string","maxLength":200,"minLength":1,"title":"Line1"},"line2":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Line2"},"city":{"type":"string","maxLength":100,"minLength":1,"title":"City"},"state":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"State","description":"State / province / region"},"postal_code":{"type":"string","maxLength":20,"minLength":1,"title":"Postal Code"},"country":{"type":"string","pattern":"^[A-Z]{2}$","title":"Country","description":"ISO 3166-1 alpha-2, e.g. US"},"phone":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Phone"}},"additionalProperties":false,"type":"object","required":["full_name","line1","city","postal_code","country"],"title":"Address"},"Availability":{"properties":{"in_stock":{"type":"boolean","title":"In Stock"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"}},"type":"object","required":["in_stock"],"title":"Availability"},"CardPayment":{"properties":{"type":{"type":"string","const":"card","title":"Type"},"cardholder_name":{"type":"string","maxLength":100,"minLength":1,"title":"Cardholder Name"},"card_number":{"type":"string","title":"Card Number","description":"12-19 digits, spaces/dashes allowed"},"exp_month":{"type":"integer","maximum":12.0,"minimum":1.0,"title":"Exp Month"},"exp_year":{"type":"integer","maximum":2100.0,"minimum":2000.0,"title":"Exp Year","description":"4 digits"},"cvc":{"type":"string","pattern":"^\\d{3,4}$","title":"Cvc"}},"additionalProperties":false,"type":"object","required":["type","cardholder_name","card_number","exp_month","exp_year","cvc"],"title":"CardPayment"},"CryptoEip3009Payment":{"properties":{"type":{"type":"string","const":"crypto_eip3009","title":"Type"},"chain":{"type":"string","enum":["eth","base","bsc"],"title":"Chain"},"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","title":"Token Address"},"from_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","title":"From Address"},"to_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","title":"To Address"},"value":{"type":"string","pattern":"^\\d{1,78}$","title":"Value","description":"Amount in token base units (integer string)"},"valid_after":{"type":"integer","minimum":0.0,"title":"Valid After","description":"Unix seconds"},"valid_before":{"type":"integer","exclusiveMinimum":0.0,"title":"Valid Before","description":"Unix seconds"},"nonce":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","title":"Nonce","description":"Random bytes32 authorization nonce"},"signature":{"type":"string","pattern":"^0x[a-fA-F0-9]{130}$","title":"Signature","description":"65-byte r||s||v hex"}},"additionalProperties":false,"type":"object","required":["type","chain","token_address","from_address","to_address","value","valid_after","valid_before","nonce","signature"],"title":"CryptoEip3009Payment","description":"EIP-3009 `transferWithAuthorization` signature (e.g. USDC)."},"CryptoPermitPayment":{"properties":{"type":{"type":"string","const":"crypto_permit","title":"Type"},"chain":{"type":"string","enum":["eth","base","bsc"],"title":"Chain"},"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","title":"Token Address"},"owner":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","title":"Owner"},"spender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","title":"Spender"},"value":{"type":"string","pattern":"^\\d{1,78}$","title":"Value","description":"Amount in token base units (integer string)"},"nonce":{"type":"string","pattern":"^\\d{1,78}$","title":"Nonce","description":"Permit nonce of owner on the token"},"deadline":{"type":"integer","exclusiveMinimum":0.0,"title":"Deadline","description":"Unix seconds"},"signature":{"type":"string","pattern":"^0x[a-fA-F0-9]{130}$","title":"Signature","description":"65-byte r||s||v hex"}},"additionalProperties":false,"type":"object","required":["type","chain","token_address","owner","spender","value","nonce","deadline","signature"],"title":"CryptoPermitPayment","description":"EIP-2612 `permit` signature; the gateway's payee/relayer is the spender."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Item":{"properties":{"asin":{"type":"string","title":"Asin"},"marketplace":{"type":"string","title":"Marketplace"},"delivery_postal_code":{"type":"string","title":"Delivery Postal Code"},"url":{"type":"string","title":"Url"},"title":{"type":"string","title":"Title"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"},"price":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"list_price":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"availability":{"$ref":"#/components/schemas/Availability"},"rating":{"$ref":"#/components/schemas/Rating"},"images":{"items":{"type":"string"},"type":"array","title":"Images"},"features":{"items":{"type":"string"},"type":"array","title":"Features"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"},"fetched_at":{"type":"string","title":"Fetched At"},"notice":{"type":"string","title":"Notice","default":"Amazon Agents Gateway is NOT an official Amazon site and is not affiliated with, endorsed by, or sponsored by Amazon. It is an independent proxy that lets AI agents buy on Amazon; order and payment details are passed directly to Amazon to complete the purchase."}},"type":"object","required":["asin","marketplace","delivery_postal_code","url","title","availability","rating","images","features","categories","fetched_at"],"title":"Item"},"Money":{"properties":{"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"currency":{"type":"string","title":"Currency"},"raw":{"type":"string","title":"Raw"}},"type":"object","required":["currency","raw"],"title":"Money"},"OrderItem":{"properties":{"asin":{"type":"string","pattern":"^[A-Za-z0-9]{10}$","title":"Asin"},"quantity":{"type":"integer","maximum":99.0,"minimum":1.0,"title":"Quantity","default":1},"marketplace":{"type":"string","enum":["amazon.com","amazon.ca","amazon.co.uk","amazon.de","amazon.fr","amazon.it","amazon.es","amazon.co.jp","amazon.com.au"],"title":"Marketplace","default":"amazon.com"},"max_unit_price":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Max Unit Price","description":"Reject the order if the live price is higher"}},"additionalProperties":false,"type":"object","required":["asin"],"title":"OrderItem"},"PurchaseRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/OrderItem"},"type":"array","maxItems":20,"minItems":1,"title":"Items"},"shipping_address":{"$ref":"#/components/schemas/Address"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Payment/billing address. Defaults to shipping_address."},"payment":{"oneOf":[{"$ref":"#/components/schemas/CardPayment"},{"$ref":"#/components/schemas/CryptoPermitPayment"},{"$ref":"#/components/schemas/CryptoEip3009Payment"}],"title":"Payment","discriminator":{"propertyName":"type","mapping":{"card":"#/components/schemas/CardPayment","crypto_eip3009":"#/components/schemas/CryptoEip3009Payment","crypto_permit":"#/components/schemas/CryptoPermitPayment"}}},"contact_email":{"anyOf":[{"type":"string","pattern":"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"},{"type":"null"}],"title":"Contact Email"},"idempotency_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":8},{"type":"null"}],"title":"Idempotency Key","description":"Retries with the same key return the same order"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Free-form data echoed to the order record"}},"additionalProperties":false,"type":"object","required":["items","shipping_address","payment"],"title":"PurchaseRequest"},"PurchaseResponse":{"properties":{"order_id":{"type":"string","title":"Order Id"},"status":{"type":"string","const":"pending","title":"Status"},"received_at":{"type":"string","title":"Received At"},"item_count":{"type":"integer","title":"Item Count"},"payment_type":{"type":"string","title":"Payment Type"},"message":{"type":"string","title":"Message"},"notice":{"type":"string","title":"Notice","default":"Amazon Agents Gateway is NOT an official Amazon site and is not affiliated with, endorsed by, or sponsored by Amazon. It is an independent proxy that lets AI agents buy on Amazon; order and payment details are passed directly to Amazon to complete the purchase."}},"type":"object","required":["order_id","status","received_at","item_count","payment_type","message"],"title":"PurchaseResponse"},"Rating":{"properties":{"average":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"}},"type":"object","title":"Rating"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}