{"openapi":"3.1.0","info":{"title":"StableGiftCards","description":"Search and buy Bitrefill gift cards, top-ups, and eSIMs. 1,500+ brands, 180+ countries.","version":"1.0.0","x-guidance":"StableGiftCards — Buy gift cards, top-ups, and eSIMs from 1,500+ brands in 180+ countries.\n\n## Flow\n\n1. POST /api/search — Find products by name, country, or category (SIWX, free)\n2. POST /api/product — Get denominations and pricing (SIWX, free)\n3. POST /api/buy — Purchase. Pays via x402 (dynamic price = product cost in USDC). Returns orders; codes are included when delivery completes within the response window, otherwise status is \"pending\".\n4. POST /api/invoice — Poll for delivery status and redemption codes (SIWX, free)\n\n## Search\n\nPOST /api/search\nBody: { \"query\": \"Netflix\", \"country\": \"US\" }\nOptional: product_type (\"giftcard\" or \"esim\"), category, in_stock, page, per_page (max 500)\nCountry must be uppercase ISO Alpha-2 (US, IT, BR).\n\n## Product Details\n\nPOST /api/product\nBody: { \"product_id\": \"netflix-usa\" }\nReturns packages array with denominations. Use the \"value\" field as package_id when buying.\n\n## Buy\n\nPOST /api/buy\nBody: { \"cart_items\": [{ \"product_id\": \"netflix-usa\", \"package_id\": \"30\" }] }\nx402-protected. First call returns 402 with the USDC price. Pay via x402 to complete.\nOn success returns invoice_id, tx_hash, and orders. Orders may have status \"pending\" if Bitrefill hasn't delivered yet — in that case, poll POST /api/invoice with the invoice_id to retrieve codes.\nUse a generous client timeout (60s+) since the response waits briefly for fast deliveries. Do not retry on client-side timeout: the x402 payment has already been captured and retrying will double-charge.\nMax 15 items per order.\n\n## Invoice\n\nPOST /api/invoice\nBody: { \"invoice_id\": \"<uuid>\" }\nReturns order status and redemption codes once fulfilled.","guidance":"StableGiftCards — Buy gift cards, top-ups, and eSIMs from 1,500+ brands in 180+ countries.\n\n## Flow\n\n1. POST /api/search — Find products by name, country, or category (SIWX, free)\n2. POST /api/product — Get denominations and pricing (SIWX, free)\n3. POST /api/buy — Purchase. Pays via x402 (dynamic price = product cost in USDC). Returns orders; codes are included when delivery completes within the response window, otherwise status is \"pending\".\n4. POST /api/invoice — Poll for delivery status and redemption codes (SIWX, free)\n\n## Search\n\nPOST /api/search\nBody: { \"query\": \"Netflix\", \"country\": \"US\" }\nOptional: product_type (\"giftcard\" or \"esim\"), category, in_stock, page, per_page (max 500)\nCountry must be uppercase ISO Alpha-2 (US, IT, BR).\n\n## Product Details\n\nPOST /api/product\nBody: { \"product_id\": \"netflix-usa\" }\nReturns packages array with denominations. Use the \"value\" field as package_id when buying.\n\n## Buy\n\nPOST /api/buy\nBody: { \"cart_items\": [{ \"product_id\": \"netflix-usa\", \"package_id\": \"30\" }] }\nx402-protected. First call returns 402 with the USDC price. Pay via x402 to complete.\nOn success returns invoice_id, tx_hash, and orders. Orders may have status \"pending\" if Bitrefill hasn't delivered yet — in that case, poll POST /api/invoice with the invoice_id to retrieve codes.\nUse a generous client timeout (60s+) since the response waits briefly for fast deliveries. Do not retry on client-side timeout: the x402 payment has already been captured and retrying will double-charge.\nMax 15 items per order.\n\n## Invoice\n\nPOST /api/invoice\nBody: { \"invoice_id\": \"<uuid>\" }\nReturns order status and redemption codes once fulfilled.","contact":{"name":"Merit Systems","url":"https://stablegiftcards.dev"}},"servers":[{"url":"https://stablegiftcards.dev"}],"tags":[{"name":"Buy"},{"name":"Invoice"},{"name":"Product"},{"name":"Search"}],"paths":{"/api/search":{"post":{"operationId":"search","summary":"Search Bitrefill products — gift cards, top-ups, eSIMs","tags":["Search"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"default":"*","type":"string","minLength":1},"country":{"type":"string","minLength":2,"maxLength":2},"product_type":{"type":"string","enum":["giftcard","esim"]},"category":{"type":"string"},"in_stock":{"default":true,"type":"boolean"},"page":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"per_page":{"default":25,"type":"integer","minimum":1,"maximum":500}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string"},"country_name":{"type":"string"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"recipient_type":{"type":"string"},"image":{"type":"string"},"description":{"type":"string"},"in_stock":{"type":"boolean"},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"},"price":{"type":"number"},"amount":{"type":"number"}},"required":["id","value","price"],"additionalProperties":false}},"range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"price_rate":{"type":"number"}},"required":["min","max","step","price_rate"],"additionalProperties":false}},"required":["id","name","country_code","country_name","currency","categories","in_stock"],"additionalProperties":false}},"total":{"type":"number"}},"required":["products","total"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/product":{"post":{"operationId":"product","summary":"Get Bitrefill product details and available denominations","tags":["Product"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string","minLength":1}},"required":["product_id"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string"},"country_name":{"type":"string"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"recipient_type":{"type":"string"},"image":{"type":"string"},"description":{"type":"string"},"in_stock":{"type":"boolean"},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"},"price":{"type":"number"},"amount":{"type":"number"}},"required":["id","value","price"],"additionalProperties":false}},"range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"price_rate":{"type":"number"}},"required":["min","max","step","price_rate"],"additionalProperties":false}},"required":["id","name","country_code","country_name","currency","categories","in_stock"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/buy":{"post":{"operationId":"buy","summary":"Buy gift cards, top-ups, or eSIMs. Pays via x402 (dynamic price = product cost in USDC). Returns orders with redemption codes if delivery completes quickly; otherwise orders have status \"pending\" — poll POST /api/invoice with the returned invoice_id to retrieve codes. For phone refills, include phone_number in the cart item.","tags":["Buy"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0","max":"500"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cart_items":{"minItems":1,"maxItems":15,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","minLength":1},"package_id":{"anyOf":[{"type":"string"},{"type":"number"}]},"quantity":{"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"phone_number":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["product_id","package_id"]}}},"required":["cart_items"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"tx_hash":{"type":"string"},"amount_usdc":{"type":"number"},"orders":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"product_name":{"type":"string"},"value":{"type":"string"},"status":{"type":"string"},"code":{"type":"string"},"pin":{"type":"string"},"link":{"type":"string"}},"required":["product_id","product_name","value","status"],"additionalProperties":false}}},"required":["invoice_id","tx_hash","amount_usdc","orders"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}}}},"/api/invoice":{"post":{"operationId":"invoice","summary":"Check invoice status and retrieve redemption codes","tags":["Invoice"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"}},"required":["invoice_id"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"status":{"type":"string"},"payment_status":{"type":"string"},"orders":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"product_name":{"type":"string"},"value":{"type":"string"},"status":{"type":"string"},"code":{"type":"string"},"pin":{"type":"string"},"link":{"type":"string"}},"required":["product_id","product_name","value","status"],"additionalProperties":false}}},"required":["invoice_id","status","payment_status","orders"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}}},"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X"}}}}