{"$schema":"https://modelcontextprotocol.io/specification/2025-06-18/server/manifest.schema.json","version":"2025-06-18","name":"Cryptorefills MCP Server","description":"Expose Cryptorefills catalog & product operations via MCP","servers":[{"name":"Cryptorefills HTTP MCP","url":"https://api.cryptorefills.com/mcp/http","transport":"http"}],"security":{"required_headers":{"User-Agent":"Cryptorefills-MCP/1.0"}},"localization":{"supported_languages":["en","es","fr","de","it","pt","zh","tr","vi","tl"],"default_language":"en","currency_formatting":true},"quick_start":{"summary":"To buy a gift card: 1. Check brands/products. 2. Get currencies. 3. Price item. 4. Validate order. 5. Create order. 6. Pay. 7. Poll status.","checklist":[{"step":"Determine product type","action":"Call listProductsForCountry; check is_dynamic (true = range, false = fixed)."},{"step":"Build payload","note":"For range: denomination='range', product_value=<amount>. For fixed: denomination=<value>."},{"step":"Common errors","fixes":["Invalid field? Use validateOrder first.","Expired? Restart from createOrder."]}],"required_headers":["User-Agent: Cryptorefills-MCP/1.0"],"alternatives":[{"name":"Interactive Mode for Small Agents","description":"For agents with limited context/memory, use the 'purchaseElicitation' tool in a loop. Start with an empty body to get session_token and first question. Respond with user's answer until status='complete'. Handles validation and order creation automatically."}]},"examples":[{"name":"Fixed-Denomination Product","description":"Buy a fixed-denomination product like Free Fire – 100 Diamonds for an Italian user, paying with USDC on Solana. This example uses an email for beneficiary_account, assuming a gift card that requires email delivery.","workflow":["1. listProductsForCountry(IT, family_name=Free Fire) → locate item where is_dynamic == false.","2. getCurrencies() → confirm 'USDC' is listed.","3. getPaymentViasWithCurrencies() → find 'USDC' with network == 'Solana'.","4. listProductsForCountry(IT, brand_name=Free Fire, coin=USDC) → read coin_amount (≈ 1.18).","5. validateOrder() with DetailedMultiProductsOrderValidationRequest","6. createOrder() with CreateOrderRequest","7. getOrderStatus() → poll every 30 s until payment_state == PaymentReceived AND order_state == Done."],"notes":"Use the single fixed denomination returned in step 4.","tips":["If order_state becomes 'WaitingForManualAction', inform the user support has been notified."],"payload_template":{"validateOrder":{"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"<FIXED_DENOMINATION e.g., 100>","brand_name":"<BRAND e.g., Free Fire>","beneficiary_account":"<EMAIL e.g., user@example.com>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"},"createOrder":{"user":{"email":"<USER_EMAIL e.g., user@example.com>","has_accepted_newsletter":false},"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"<FIXED_DENOMINATION e.g., 100>","brand_name":"<BRAND e.g., Free Fire>","beneficiary_account":"<EMAIL e.g., user@example.com>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"}}},{"name":"Range-Based Product","description":"Buy a range-based product like Amazon.it gift card with a custom 50 EUR value, paid in USDC on Solana. This example uses an email for beneficiary_account, as it's a gift card requiring email delivery.","workflow":["1. listProductsForCountry(IT, brand_name=Amazon) → item where is_dynamic == true, range min=5 EUR.","2. getCurrencies() → confirm 'USDC' supported.","3. getPaymentViasWithCurrencies() → choose network (e.g., 'Solana' or 'Polygon').","4. /v4/products/price?brand_name=Amazon&face_value=50&coin=USDC (price-calc helper) → get coin_amount.","5. validateOrder() with 1 × 50 EUR Amazon deliverable.","6. createOrder()","7. getOrderStatus() → monitor until Done (or handle Expired/Canceled/WaitingForManualAction)."],"tips":["When range.min ≤ product_value ≤ range.max the request is valid.","If order_state becomes 'WaitingForManualAction', inform the user support has been notified."],"payload_template":{"validateOrder":{"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"range","product_value":"<AMOUNT e.g., 50>","brand_name":"<BRAND e.g., Amazon.it>","beneficiary_account":"<EMAIL e.g., user@example.com>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"},"createOrder":{"user":{"email":"<USER_EMAIL e.g., user@example.com>","has_accepted_newsletter":false},"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"range","product_value":"<AMOUNT e.g., 50>","brand_name":"<BRAND e.g., Amazon.it>","beneficiary_account":"<EMAIL e.g., user@example.com>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"}}},{"name":"Gift Card (Email Required)","description":"Buy a gift card like Netflix, which requires an email in beneficiary_account for delivery. Assuming fixed denomination (e.g., 50 EUR) and payment with USDC on Solana.","workflow":["1. listBrands(country_code=IT) → confirm 'Netflix' available.","2. listProductsForCountry(IT, brand_name=Netflix) → select fixed denomination (is_dynamic=false).","3. getCurrencies() → confirm 'USDC' supported.","4. getPaymentViasWithCurrencies() → choose 'USDC' on 'Solana'.","5. listProductsForCountry(IT, brand_name=Netflix, coin=USDC) → get coin_amount.","6. validateOrder() with email in beneficiary_account.","7. createOrder()","8. getOrderStatus() → poll until Done."],"tips":["Ensure beneficiary_account is a valid email format."],"payload_template":{"validateOrder":{"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"<DENOMINATION e.g., 50>","brand_name":"<BRAND e.g., Netflix>","beneficiary_account":"<EMAIL e.g., user@example.com>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"},"createOrder":{"user":{"email":"<USER_EMAIL e.g., user@example.com>","has_accepted_newsletter":false},"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"<DENOMINATION e.g., 50>","brand_name":"<BRAND e.g., Netflix>","beneficiary_account":"<EMAIL e.g., user@example.com>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"}}},{"name":"Mobile Top-Up (Phone Required)","description":"Buy a mobile top-up like Vodafone 20 EUR, which requires a phone number in beneficiary_account for delivery. Assuming fixed denomination and payment with USDC on Solana.","workflow":["1. listBrands(country_code=IT) → confirm 'Vodafone' available for mobile top-up.","2. listProductsForCountry(IT, brand_name=Vodafone) → select fixed denomination (is_dynamic=false).","3. getCurrencies() → confirm 'USDC' supported.","4. getPaymentViasWithCurrencies() → choose 'USDC' on 'Solana'.","5. listProductsForCountry(IT, brand_name=Vodafone, coin=USDC) → get coin_amount.","6. validateOrder() with phone in beneficiary_account (E.164 format, e.g., +393123456789).","7. createOrder()","8. getOrderStatus() → poll until Done."],"tips":["Ensure beneficiary_account is a valid phone number in E.164 format (e.g., +[country code][number])."],"payload_template":{"validateOrder":{"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"<DENOMINATION e.g., 20>","brand_name":"<BRAND e.g., Vodafone>","beneficiary_account":"<PHONE e.g., +393123456789>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"},"createOrder":{"user":{"email":"<USER_EMAIL e.g., user@example.com>","has_accepted_newsletter":false},"payment":{"type":"via","payment_via":"USER_WALLET","coin":"<COIN e.g., USDC>","network":"<NETWORK e.g., Solana>"},"deliveries":[{"denomination":"<DENOMINATION e.g., 20>","brand_name":"<BRAND e.g., Vodafone>","beneficiary_account":"<PHONE e.g., +393123456789>","country_code":"<COUNTRY_CODE e.g., IT>"}],"lang":"<LANG e.g., en>"}}},{"name":"Interactive Gift Card Purchase","description":"Buy an Amazon.it €50 gift card interactively, paying with USDC on Solana.","workflow":["1. Call purchaseElicitation({}) → question: 'What kind of product...?', options: ['giftcard', 'mobile_topup']","2. User answers 'giftcard' → Call with {session_token: '...', answer: 'giftcard'} → next question: 'In which country?'","3. Continue: 'IT' → 'What brand?' → 'Amazon.it' → 'What amount?' → '50' → 'Enter email...' → 'user@example.com' → 'What coin?' → 'USDC' → 'On what blockchain?' → 'Solana' → 'Enter user email...' → 'user@example.com' → 'This is the recap... proceed?' → 'yes'","4. Final response: status='complete', payment_details: {walletAddress: '...', coinAmount: '50.5', ...}, next_step: 'Send 50.5 USDC to ... and poll /v5/orders/{id}'"],"tips":["If error (e.g., invalid brand), use fix/suggestions to guide user.","Handle 'back' if user wants to change answers."]},{"name":"Interactive Mobile Top-Up","description":"Top up Vodafone €20 interactively, paying with USDC on Solana.","workflow":["1. Call purchaseElicitation({}) → question: 'What kind of product...?', options: ['giftcard', 'mobile_topup']","2. User answers 'mobile_topup' → Call with {session_token: '...', answer: 'mobile_topup'} → next question: 'In which country?'","3. Continue: 'IT' → 'What brand?' → 'Vodafone' → 'What amount?' → '10' → 'Enter email...' → 'user@example.com' → 'What coin?' → 'USDC' → 'On what blockchain?' → 'Solana' → 'Enter user email...' → 'user@example.com' → 'This is the recap... proceed?' → 'yes'","4. Final response: status='complete', payment_details: {walletAddress: '...', coinAmount: '11.5', ...}, next_step: 'Send 11.5 USDC to ... and poll /v5/orders/{id}'"]},{"name":"Prompted Gift Card Purchase","description":"Buy an Amazon.it 10 EUR gift card using a natural-language prompt.","workflow":["1. Invoke purchaseGiftCard with prompt: 'use cryptorefills-purchaseElicitation and buy an Amazon.it 10 EUR giftcard. pay with USDC on Solana. email: simonluca.landi@gmail.com'.","2. Internally, the server parses the prompt and drives purchaseElicitation with answers: 'giftcard', 'IT', 'Amazon.it', '10', 'simonluca.landi@gmail.com', 'USDC', 'Solana', 'yes'.","3. Final response: status='complete', payment_details: {coinSymbol: 'USDC', coinAmount: '10.5', walletAddress: '...', network: 'Solana'}, next_step: 'Send 10.5 USDC to ... and poll /v5/orders/{id}'."]}],"workflows":[{"name":"purchase_gift_card_or_mobile_topup","description":"Complete workflow to purchase gift cards or mobile top-ups using cryptocurrency","steps":[{"step":1,"description":"Browse available brands in a country","tool":"listBrands","required":true,"output":"Extract brand names"},{"step":2,"description":"Browse available products for a brand","tool":"listProductsForCountry","required":true,"input":"Use country_code from step 1, must specify family_name=brand name from step 1","output":"Extract denomination, family name, brand names, and check if products have fixed denomination or range (is_dynamic=true with range object)"},{"step":3,"description":"Get list of supported cryptocurrencies","tool":"getCurrencies","required":true,"output":"Available cryptocurrency options (BTC, ETH, USDT, SOL, etc.)","note":"Use network information to understand which blockchain will be used (e.g., Solana, Polygon, Ethereum)"},{"step":4,"description":"Get product pricing with selected cryptocurrency","required":true,"decision_logic":"Check the is_dynamic field from step 1 results to determine which tool to use","tools":[{"name":"listProductsForCountry","condition":"For fixed denomination products (is_dynamic=false)","usage":"Most common case - products with predetermined denominations","input":"Add coin parameter to get prices in specific cryptocurrency","example":"GET /v5/products/country/IT?brand_name=Free%20Fire&coin=USDC&category=games","output":"Products array with coin_amount field showing exact price in requested cryptocurrency","payment_method_format":"Returns payment_method like 'USDC-MATIC' indicating currency and network","network_mapping":{"USDC-MATIC":"Polygon (Matic) network","USDC-SOL":"Solana network","USDC-ETH":"Ethereum Mainnet","USDC-ARB":"Arbitrum network","USDC-AVAX":"Avalanche network","BTC":"Bitcoin Mainnet"}},{"name":"getProductPrice","condition":"Only for range-based products (is_dynamic=true) where customer selects face_value","usage":"Less common - for products like Amazon gift cards where customer chooses amount within min/max range","input":"Use when product has range object with min/max values. Customer must select face_value within range.","example":"GET /v4/products/price?brand_name=Amazon.it&country_code=IT&face_value=50&coin=USDC","output":"Single ProductResponse with coin_amount for the selected face_value","required_fields":["brand_name","country_code","face_value","coin"]}]},{"step":5,"description":"Validate order before creation","tool":"validateOrder","required":true,"input":"Create DetailedMultiProductsOrderValidationRequest with products array containing each item. For fixed products use original denomination, for denomination 'range' products, add the selected face_value from step 4. Each product entry **must** include `beneficiary_account` (e-mail or phone)","output":"Check validation response for any problems or errors before proceeding","payment_field_format":{"type":"Discriminator for payment path: 'via' | 'binance_pay'","payment_via":"Required when type='via'. Value from /v3/payment_vias","coin":"Cryptocurrency symbol (e.g., 'USDC')","network":"Blockchain network name (e.g., 'Solana')"}},{"step":6,"description":"Create the actual order","tool":"createOrder","required":true,"input":"Use CreateOrderRequest with validated deliveries from step 5, payment details from step 3, and user information","output":"Get order_id, payment wallet address, QR codes, and payment details"},{"step":7,"description":"Monitor order status until completion","tool":"getOrderStatus","required":true,"input":"Use order_id from step 6","output":["Stop polling when payment_state == \"PaymentReceived\" AND order_state == \"Done\".","Then read the elements of deliveries[]. The deliverable object contains:","  • pin_code            – gift-card code or an https URL","  • pin_serial          – (optional) serial number","  • security_code       – (optional) security / CVV code","  • pin_usage_instructions – human-readable HTML instructions","Redemption tip – When pin_code starts with “http” or “https”, open it in the browser rather than showing it as plain text.","Other terminal outcomes:","• order_state == \"Expired\"  – Payment window closed; ask user to create a new order.","• order_state == \"WaitingForManualAction\" – Delivery issue; support team is handling it.","• order_state == \"Canceled\" – User canceled; workflow ends."],"repeat":"Poll every 30 s until the above final states are reached"}],"examples":[{"name":"Fixed-Denomination Product","description":"Buy **Free Fire – 100 Diamonds** for an Italian user, paying with USDC on Solana.","workflow":["1. listProductsForCountry(IT, family_name=Free Fire) → locate item where is_dynamic == false.","2. getCurrencies()                       → confirm 'USDC' is listed.","3. getPaymentViasWithCurrencies()        → find 'USDC' with network == 'Solana'.","4. listProductsForCountry(IT, brand_name=Free Fire, coin=USDC) → read coin_amount (≈ 1.18).","5. validateOrder()  with DetailedMultiProductsOrderValidationRequest","6. createOrder()    with CreateOrderRequest","7. getOrderStatus() → poll every 30 s until payment_state == PaymentReceived AND order_state == Done."],"notes":"Use the single fixed denomination returned in step 4.","tips":["If order_state becomes 'WaitingForManualAction', inform the user support has been notified."]},{"name":"Range-Based Product","description":"Buy **Amazon.it** gift card with a custom 50 EUR face value, paid in USDC.","workflow":["1. listProductsForCountry(IT, brand_name=Amazon.it) → item where is_dynamic == true, range min=5 EUR.","2. getCurrencies()                       → confirm 'USDC' supported.","3. getPaymentViasWithCurrencies()        → choose network (e.g., 'Solana' or 'Polygon').","4. /v4/products/price?brand_name=Amazon.it&face_value=50&coin=USDC (price-calc helper) → get coin_amount. Pay attention to use '&' and not '&amp' when building the url.","5. validateOrder()  with 1 × 50 EUR Amazon deliverable.","6. createOrder()","7. getOrderStatus() → monitor until Done (or handle Expired/Canceled/WaitingForManualAction)."],"tips":["When range.min ≤ face_value ≤ range.max the request is valid.","If order_state becomes 'WaitingForManualAction', inform the user support has been notified."]},{"name":"Quick-Flow Example","description":"Buy **Amazon.it Italy €2** gift card, pay with **USDC on Solana**.","workflow":["1. listBrands(country_code=IT)           → confirm 'Amazon.it' available.","2. listProductsForCountry(IT, brand_name=Amazon.it, coin=USDC) → select denomination == 2 EUR.","3. getPaymentViasWithCurrencies()        → verify USDC / Solana combo.","4. validateOrder()  with quantity=1, face_value=2 EUR.","5. createOrder()    returns order_id + qr_url","6. Display qr_url   to the end user for payment.","7. getOrderStatus(order_id)              → poll:","   • If payment_state == PaymentReceived && order_state == Done ⇒ stop.","   • If order_state == Expired ⇒ notify user payment window closed.","   • If order_state == WaitingForManualAction ⇒ tell user support has emailed them."]}]},{"name":"browse_catalog","description":"Browse available products without purchasing","steps":[{"step":1,"tool":"listBrands","description":"See all available brands for a country"},{"step":2,"tool":"listProductsForCountry","description":"Get detailed product information","input":"Use country_code from step 1, must specify family_name=brand name from step 1"}]},{"name":"interactive_purchase","description":"Simplified, step-by-step interactive purchase for gift cards or mobile top-ups. Ideal for small-footprint agents. Use this instead of 'purchase_gift_card_or_mobile_topup' if you prefer guided elicitation over discrete tool calls.","steps":[{"step":1,"description":"Start a new session","tool":"purchaseElicitation","required":true,"input":"Empty body {} (session_token will be generated).","output":"Get status='continue', session_token, first question (e.g., 'What kind of product do you want to buy?'), expected_format, and options (e.g., ['giftcard', 'mobile_topup'])."},{"step":2,"description":"Ask user the question and get their answer","note":"Present question to user, enforce expected_format, show options if provided."},{"step":3,"description":"Submit answer and continue","tool":"purchaseElicitation","required":true,"input":"Body with session_token (from previous), answer (user's response). Use action='back' if user wants to revert.","output":"If valid: next question. If error: handle error/fix/suggestions. If complete: get payment_details and next_step (e.g., send payment and poll order).","repeat":"Loop steps 2-3 until status='complete' or unrecoverable error. Typical steps: product type → country → brand → amount → beneficiary → coin → network → user email → confirmation."},{"step":4,"description":"Handle completion","note":"On complete: Instruct user to pay using payment_details (walletAddress, coinAmount, etc.). Poll GET /v5/orders/{orderId} (from next_step) until done. Note: session_token is not returned as the session ends."}]},{"name":"prompted_gift_card_purchase","description":"Purchase a gift card using a natural-language prompt that specifies brand, amount, country, cryptocurrency, network, and email. Uses the purchaseGiftCard prompt to drive purchaseElicitation.","steps":[{"step":1,"description":"Invoke the purchaseGiftCard prompt","prompt":"purchaseGiftCard","required":true,"input":"Natural-language prompt (e.g., 'buy an Amazon.it 10 EUR giftcard, pay with USDC on Solana, email: simonluca.landi@gmail.com') or structured arguments: {'brand': 'Amazon.it', 'amount': '10', 'country': 'IT', 'coin': 'USDC', 'network': 'Solana', 'email': 'simonluca.landi@gmail.com'}.","output":"Final order details (payment_details, next_step) or error."}]}],"prompts":[{"name":"purchaseGiftCard","title":"Purchase a Gift Card","description":"Guides the AI to purchase a gift card using the purchaseElicitation tool. Provide the brand, amount, country, cryptocurrency, network, and delivery email in a natural-language prompt or structured arguments. Example: 'buy an Amazon.it 10 EUR giftcard, pay with USDC on Solana, email: user@example.com'.","arguments":[{"name":"brand","type":"string","description":"Brand of the gift card (e.g., 'Amazon.it').","required":true},{"name":"amount","type":"string","description":"Gift card amount (e.g., '10' for 10 EUR).","required":true},{"name":"country","type":"string","description":"Country code for the gift card (e.g., 'IT' for Italy).","required":true},{"name":"coin","type":"string","description":"Cryptocurrency for payment (e.g., 'USDC').","required":true},{"name":"network","type":"string","description":"Blockchain network for payment (e.g., 'Solana').","required":true},{"name":"email","type":"string","description":"Email for gift card delivery (e.g., 'user@example.com').","required":true}],"tools":["purchaseElicitation"],"workflow":["1. Parse the prompt to extract brand, amount, country, coin, network, and email.","2. Start a purchaseElicitation session with an empty body to get session_token and first question.","3. Answer questions in order: 'giftcard' (product type), country, brand, amount, email, coin, network, 'yes' (confirmation).","4. Repeat purchaseElicitation calls with session_token and answers until status='complete'.","5. Return payment_details and next_step for the user to complete payment."]}],"tools":[{"name":"purchaseElicitation","description":"Interactive, stateful endpoint to guide small-footprint AI agents through a purchase flow for gift cards or mobile top-ups. Call repeatedly with the same session_token until 'status' is 'complete' or 'error'. For the first call, provide an empty 'body': {} (session_token will be generated and returned). Provide 'answer' in the body to respond to the current question. Use 'action: back' in the body to go to the previous step. Handles product type selection, country, brand, amount, beneficiary, coin, network, user email, and final confirmation/validation/order creation.","endpoint":{"method":"POST","path":"/mcp/purchase_elicitation","body":{"type":"object","properties":{"session_token":{"type":"string","description":"Unique token for the session (returned in first response; required for subsequent calls)."},"answer":{"type":"string","description":"User's response to the current question (e.g., 'giftcard', 'IT', 'Amazon.it', '50', 'user@example.com', 'USDC', 'SOLANA', 'yes')."},"action":{"type":"string","description":"Optional action like 'back' to revert to the previous step.","enum":["back"]}},"required":[]}},"response":{"type":"object","properties":{"status":{"type":"string","enum":["continue","complete","error"],"description":"'continue' = more questions; 'complete' = order created; 'error' = validation or execution failed."},"session_token":{"type":["string","null"],"description":"Token for this session (returned for continue; may be null for complete or error)."},"question":{"type":"string","description":"Next question to ask the user (if status=continue)."},"expected_format":{"type":"string","description":"Expected format for the answer (if status=continue)."},"options":{"type":"array","items":{"type":"string"},"description":"Suggested options for the answer (if applicable, for status=continue)."},"previous_answers":{"type":"object","description":"Map of data collected so far (e.g., {'country': 'IT', 'brand': 'Amazon.it'})."},"error":{"type":"string","description":"Error message (if status=error)."},"fix":{"type":"string","description":"Suggestion to fix the error (if status=error)."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative suggestions (if status=error)."},"next_step":{"type":"string","description":"Instructions for payment/polling (if status=complete)."},"payment_details":{"type":"object","properties":{"walletAddress":{"type":"string"},"coinSymbol":{"type":"string"},"coinAmount":{"type":"string"},"network":{"type":"string"}},"description":"Payment info (if status=complete)."}},"required":["status"],"if":{"properties":{"status":{"const":"error"}}},"then":{"required":["status","error","fix"]},"else":{"if":{"properties":{"status":{"const":"continue"}}},"then":{"required":["status","session_token","question","expected_format","previous_answers"]},"else":{"required":["status","next_step","payment_details"]}}}},{"name":"getCurrencies","description":"Fetch supported crypto currencies","endpoint":{"url":"https://api.cryptorefills.com/v3/currencies","method":"GET"},"response":{"type":"array","items":{"$ref":"#/definitions/BaseCurrency"}}},{"name":"listBrands","description":"Fetch available gift-card and mobile top-ups brands for a given country","endpoint":{"url":"https://api.cryptorefills.com/v2/brands","method":"GET","query":{"type":"object","properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","examples":["US","GB","FR","DE"]},"cid":{"type":"string"},"promo_code":{"type":"string"}},"required":["country_code"],"additionalProperties":false}},"response":{"type":"object","properties":{"country_code":{"type":"string"},"categories":{"type":"array","items":{"$ref":"#/definitions/CategoryModel"}},"all_brands":{"type":"array","items":{"$ref":"#/definitions/BrandModel"}},"last_user_purchases":{"type":"array","items":{"$ref":"#/definitions/BrandModel"}},"suggestions":{"type":"array","items":{"$ref":"#/definitions/BrandModel"}}},"required":["country_code","categories","all_brands","last_user_purchases","suggestions"]}},{"name":"listProductsForCountry","description":"List all products in a country, optionally filtering by brand, family, coin, payment method, language, or promo code","endpoint":{"url":"https://api.cryptorefills.com/v5/products/country/{country_code}","method":"GET","pathParameters":{"type":"object","properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","examples":["US","GB","FR","DE"]}},"required":["country_code"],"additionalProperties":false},"query":{"type":"object","properties":{"brand_name":{"type":"string"},"family_name":{"type":"string"},"coin":{"type":"string"},"payment_method":{"type":"string"},"lang":{"type":"string"},"promo_code":{"type":"string"}},"required":[],"additionalProperties":false}},"response":{"type":"array","items":{"$ref":"#/definitions/ProductsForBrandResponse"}}},{"name":"getPaymentViasWithCurrencies","description":"Fetch possible payment methods and supported currencies/networks","endpoint":{"url":"https://api.cryptorefills.com/v3/payment_vias","method":"GET"},"response":{"type":"array","items":{"$ref":"#/definitions/PaymentViaWithCurrencies"}}},{"name":"getProductPrice","description":"Get pricing for range-based products where customer can select face value within min/max range","endpoint":{"url":"https://api.cryptorefills.com/v4/products/price","method":"GET","query":{"type":"object","properties":{"brand_name":{"type":"string","description":"Brand name of the product"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","examples":["US","GB","FR","DE"]},"face_value":{"type":"number","description":"Selected face value amount within the product's min/max range"},"coin":{"type":"string","description":"Cryptocurrency to get price in (e.g., BTC, ETH, USDT, SOL)"},"promo_code":{"type":"string","description":"Optional promotional code for discounts"}},"required":["brand_name","country_code","face_value","coin"],"additionalProperties":false}},"response":{"$ref":"#/definitions/ProductResponse"}},{"name":"validateOrder","description":"Validate a potential order against minimum amount and business rules","endpoint":{"url":"https://api.cryptorefills.com/v5/orders/validations","method":"POST","body":{"$ref":"#/definitions/DetailedMultiProductsOrderValidationRequest"}},"response":{"$ref":"#/definitions/DetailedMultiProductsOrderValidationResponse"}},{"name":"createOrder","description":"Submit a new order with selected products and payment method","endpoint":{"url":"https://api.cryptorefills.com/v5/orders","method":"POST","body":{"$ref":"#/definitions/CreateOrderRequest"}},"response":{"$ref":"#/definitions/MultiProductsOrderResponse"}},{"name":"getOrderStatus","description":"Retrieve the status and details of a submitted order","endpoint":{"url":"https://api.cryptorefills.com/v5/orders/{order_id}","method":"GET","pathParameters":{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"],"additionalProperties":false}},"response":{"$ref":"#/definitions/MultiProductsOrderResponse"}},{"name":"searchProducts","description":"Search products by text query across brands and categories in a given country","endpoint":{"url":"https://api.cryptorefills.com/v2/search/{country_code}","method":"GET","pathParameters":{"type":"object","properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","examples":["US","GB","FR","DE"]}},"required":["country_code"],"additionalProperties":false},"query":{"type":"object","properties":{"q":{"type":"string","description":"Search query"},"lang":{"type":"string","examples":["en","it","de","zh"]}},"required":["q"],"additionalProperties":false}}}],"definitions":{"CategoryModel":{"type":"object","properties":{"kind":{"type":"string"},"category":{"type":["string","null"]},"brands":{"type":"array","items":{"$ref":"#/definitions/BrandModel"}},"popular_brands":{"type":"array","items":{"$ref":"#/definitions/BrandModel"}}},"required":["kind","brands","popular_brands"]},"BrandModel":{"type":"object","properties":{"family":{"type":"string"},"brand_id":{"type":"string"},"brand":{"type":"string"},"logo_url":{"type":"string","format":"uri"},"logo_base_url":{"type":"string","format":"uri"},"bg_color":{"type":"string"},"category":{"type":"string"},"kind":{"type":"string"},"is_out_of_stock":{"type":"boolean"},"min":{"type":["string","null"]},"max":{"type":["string","null"]},"country_code":{"type":"string"},"additional_categories":{"type":"array","items":{"type":"string"}},"promotion":{"type":["object","null"]},"product_type":{"type":"string"}},"required":["family","brand_id","brand","logo_url","category","is_out_of_stock","country_code","product_type"]},"ProductsForBrandResponse":{"type":"object","properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country code","examples":["US","GB","FR","DE"]},"category":{"type":"string"},"additional_categories":{"type":"array","items":{"type":"string"}},"kind":{"type":"string"},"default_denomination":{"type":"string"},"products":{"type":"array","items":{"$ref":"#/definitions/ProductResponse"}},"family":{"type":"string"},"brand_id":{"type":"string"},"brand":{"type":"string"},"is_out_of_stock":{"type":"boolean"},"logo_url":{"type":"string","format":"uri"},"logo_base_url":{"type":"string","format":"uri"},"product_tc":{"type":"string"},"redeem_method":{"type":"array","items":{"type":"string"}},"rich_description":{"$ref":"#/definitions/RichDescription"},"product_type":{"type":"string"},"promotion":{"type":["object","null"]}},"required":["country_code","category","additional_categories","kind","default_denomination","products","family","brand_id","brand","is_out_of_stock","logo_url","logo_base_url","product_tc","redeem_method","product_type"]},"ProductResponse":{"type":"object","properties":{"product_id":{"type":"string"},"is_dynamic":{"type":"boolean"},"range":{"$ref":"#/definitions/Range"},"customer_specific":{"$ref":"#/definitions/CustomerSpecific"},"denomination":{"type":["string","null"]},"localized_denomination":{"type":["string","null"]},"coin_amount":{"type":["string","null"]},"coin":{"type":"string"},"original_coin_amount":{"type":["string","null"]},"face_value":{"$ref":"#/definitions/FaceValue"},"payment_method":{"type":"string"},"delivery_type":{"type":"string"},"points":{"type":"string"},"benefits":{"type":["array","null"],"items":{"$ref":"#/definitions/Benefit"}},"additional_details":{"type":["object","null"]},"valid_regions":{"type":"array","items":{"type":"string"}},"product_type":{"type":"string"}},"required":["product_id","is_dynamic","coin","payment_method","delivery_type","points","product_type"]},"Range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"step_size":{"type":"number"},"default":{"type":"string"}},"required":["min","max","currency","step_size","default"]},"CustomerSpecific":{"type":"object","properties":{"account":{"type":"string"},"face_value":{"type":"number"}},"required":["account","face_value"]},"FaceValue":{"type":"object","properties":{"currency_code":{"type":"string"},"amount":{"oneOf":[{"$ref":"#/definitions/Fixed"},{"$ref":"#/definitions/FaceValueRange"}]}},"required":["currency_code","amount"]},"Fixed":{"type":"object","properties":{"price":{"type":"string","description":"Display label for fixed denomination (e.g., '5 EUR', '3 months subscription', '100 diamonds + 10 free')."}},"required":["price"]},"FaceValueRange":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"Benefit":{"type":"object","properties":{"type":{"type":"string"},"unit_type":{"type":"string"},"unit":{"type":"string"},"amount":{"$ref":"#/definitions/Amount"},"additional_information":{"type":"string"}},"required":["type","unit_type","unit","amount","additional_information"]},"Amount":{"type":"object","properties":{"base":{"$ref":"#/definitions/IAmount"},"promotion_bonus":{"$ref":"#/definitions/IAmount"},"total_excluding_tax":{"$ref":"#/definitions/IAmount"},"total_including_tax":{"$ref":"#/definitions/IAmount"}},"required":["base","promotion_bonus","total_excluding_tax","total_including_tax"]},"IAmount":{"type":"object","additionalProperties":true},"PaymentViaWithCurrencies":{"type":"object","properties":{"name":{"type":"string"},"logo_url":{"type":["string","null"]},"currencies":{"type":"array","items":{"$ref":"#/definitions/CurrencyWithNetwork"}}},"required":["name","currencies"]},"CurrencyWithNetwork":{"type":"object","properties":{"name":{"type":"string"},"logo_url":{"type":"string"},"threshold":{"type":["string","null"]},"networks":{"type":"array","items":{"$ref":"#/definitions/PaymentNetwork"}},"is_suspended":{"type":"boolean"}},"required":["name","logo_url","networks","is_suspended"]},"PaymentNetwork":{"type":"object","properties":{"name":{"type":"string","examples":["Base","Ethereum","Mainnet","Solana"]},"chain_id":{"type":["integer","null"]},"logo_url":{"type":["string","null"]},"threshold":{"type":["string","null"]},"smart_contract_engine":{"type":["string","null"]},"base_token":{"type":["string","null"],"examples":["ETH","SOL"]},"smart_contract":{"type":["object","null"]},"estimated_transfer_cost":{"type":["string","null"]}},"required":["name"]},"ISmartContract":{"type":"object","properties":{"address":{"type":"string"},"decimals":{"type":"integer"},"symbol":{"type":"string"}},"required":["address","decimals","symbol"]},"RichDescription":{"type":"object","properties":{"markup":{"type":"string"},"description":{"type":["string","null"]},"how_to_redeem":{"type":["string","null"]},"term_and_conditions":{"type":["string","null"]},"country_code":{"type":["string","null"]},"locale":{"type":"string"},"note":{"type":["string","null"]},"redeem_geo":{"type":["string","null"]}},"required":[]},"DetailedMultiProductsOrderValidationRequest":{"type":"object","properties":{"user":{"$ref":"#/definitions/UserOptional"},"payment":{"$ref":"#/definitions/IPayment"},"coupon_code":{"type":["string","null"]},"promo_code":{"type":["string","null"]},"nft_codes":{"type":["array","null"],"items":{"$ref":"#/definitions/NFTCode"}},"acquisition":{"$ref":"#/definitions/AcquisitionOptional"},"deliveries":{"type":"array","items":{"$ref":"#/definitions/ProductDeliverable"}},"lang":{"type":["string","null"]},"time_zone":{"type":["string","null"]},"binance_sku":{"type":["string","null"]},"external_store":{"$ref":"#/definitions/ExternalStoreOptional"},"state_transition_notification_url":{"type":["string","null"],"format":"uri"},"refund_wallet_address":{"type":["string","null"]}},"required":["payment","deliveries"],"additionalProperties":false},"UserOptional":{"oneOf":[{"$ref":"#/definitions/User"},{"type":"null"}]},"User":{"type":"object","properties":{"email":{"type":"string"},"has_accepted_newsletter":{"type":"boolean"},"referral_code":{"type":["string","null"]}},"required":["email"],"additionalProperties":false},"IPayment":{"type":"object","oneOf":[{"description":"User pays directly from an on-chain wallet","properties":{"type":{"const":"via"},"payment_via":{"type":"string","examples":["USER_WALLET"]},"coin":{"type":"string","examples":["USDC","USDT","BTC","SOL","WLD"]},"network":{"type":"string","examples":["Solana","Polygon (Matic)","Mainnet"]}},"required":["type","payment_via","coin","network"],"additionalProperties":false},{"description":"User pays through Binance Pay","properties":{"type":{"const":"binance_pay"},"coin":{"type":"string","examples":["USDT"]}},"required":["type","coin"],"additionalProperties":false}]},"NFTCode":{"type":"object","properties":{"tokenId":{"type":"string"},"contract_address":{"type":"string"},"network":{"type":"string"},"permit":{"$ref":"#/definitions/PermitOptional"}},"required":["tokenId","contract_address","network"],"additionalProperties":false},"PermitOptional":{"oneOf":[{"$ref":"#/definitions/Permit"},{"type":"null"}]},"Permit":{"type":"object","properties":{"signature":{"type":"string"},"deadline":{"type":"integer"}},"required":["signature","deadline"],"additionalProperties":false},"AcquisitionOptional":{"oneOf":[{"$ref":"#/definitions/Acquisition"},{"type":"null"}]},"Acquisition":{"type":"object","properties":{"gclid":{"type":["string","null"]},"cid":{"type":["string","null"]},"utm_source":{"type":["string","null"]},"utm_campaign":{"type":["string","null"]},"utm_medium":{"type":["string","null"]},"utm_term":{"type":["string","null"]},"utm_content":{"type":["string","null"]},"click_id":{"type":["string","null"]},"referer":{"type":["string","null"]},"session_id":{"type":["string","null"]},"conversion_flow":{"type":["string","null"]}},"additionalProperties":false},"ExternalStoreOptional":{"oneOf":[{"$ref":"#/definitions/ExternalStore"},{"type":"null"}]},"ExternalStore":{"type":"object","properties":{"coin_name":{"type":"string"},"coin_amount":{"type":"number"}},"required":["coin_name","coin_amount"],"additionalProperties":false},"DetailedMultiProductsOrderValidationResponse":{"type":"object","properties":{"coin":{"type":"string"},"coin_amount":{"type":"string"},"original_coin_amount":{"type":"string"},"coupon_code":{"type":["string","null"]},"deliveries":{"type":"array","items":{"$ref":"#/definitions/Delivery"}},"payment_fee":{"$ref":"#/definitions/PaymentFee"},"points":{"$ref":"#/definitions/Points"},"nft_codes":{"$ref":"#/definitions/NFTCodeSpendingSummary"},"summary":{"$ref":"#/definitions/OrderSummary"},"problems":{"type":"array","items":{"$ref":"#/definitions/IEnrichedProblem"}},"is_payment_processor_external":{"type":"boolean"}},"required":["coin","coin_amount","original_coin_amount","deliveries","payment_fee","points","summary","is_payment_processor_external"],"additionalProperties":false},"CreateOrderRequest":{"type":"object","properties":{"user":{"$ref":"#/definitions/User"},"payment":{"$ref":"#/definitions/IPayment"},"coupon_code":{"type":["string","null"]},"promo_code":{"type":["string","null"]},"nft_codes":{"type":["array","null"],"items":{"$ref":"#/definitions/NFTCode"}},"acquisition":{"$ref":"#/definitions/AcquisitionOptional"},"deliveries":{"type":"array","items":{"$ref":"#/definitions/ProductDeliverable"}},"lang":{"type":["string","null"]},"time_zone":{"type":["string","null"]},"binance_sku":{"type":["string","null"]},"external_store":{"$ref":"#/definitions/ExternalStoreOptional"},"state_transition_notification_url":{"type":["string","null"],"format":"uri"},"refund_wallet_address":{"type":["string","null"]}},"required":["user","payment","deliveries"],"additionalProperties":false},"MultiProductsOrderResponse":{"type":"object","description":"Full payload returned after creating an order or polling its status.","properties":{"order_id":{"type":"string","description":"UUID v4 that uniquely identifies the order"},"created_at":{"type":"integer","format":"int64","description":"Unix epoch (seconds) when the order was created"},"wallet_address":{"type":"string","description":"Destination wallet address (if applicable)"},"payment_method":{"type":"string"},"network":{"type":"string","description":"Blockchain / network (e.g. 'Solana')"},"coin":{"type":"string","description":"Ticker of the settlement currency"},"coin_amount":{"type":"string"},"original_price":{"type":"string"},"qr_url":{"type":"string","format":"uri","description":"uri to retrieve a QR code that can be used to start the payment"},"qr_text":{"type":"string"},"sent_coin_amount":{"type":["string","null"]},"payment_state":{"type":"string","enum":["WalletRequested","WalletCreated","PaymentRequested","PaymentStarted","WaitingForComplianceReport","PaymentQuarantined","PaymentReceived","PartialPaymentStarted","Failed","WaitingForExpiry","WaitingForExpiryAfterPaymentDetection","Expired","ExpiredAfterPaymentDetection","PaymentCanceled"]},"deliveries":{"type":"array","items":{"$ref":"#/definitions/Delivery"}},"order_state":{"type":"string","enum":["WaitingForPayment","PaymentStarted","PaymentFailed","WaitingForNFTCards","NFTCardsSpent","WaitingForDelivery","WaitingForCoupon","Refunded","Completed","WaitingForManualAction","Done","Expired","Canceled"]},"missing_amount":{"type":["string","null"]},"missing_amount_qr_text":{"type":["string","null"]},"missing_amount_qr_url":{"type":["string","null"],"format":"uri"},"received_amount":{"type":["string","null"]},"checkout_url":{"type":["string","null"],"format":"uri","description":"when present, redirect the use here to start the payment"},"nft_codes":{"$ref":"#/definitions/NFTCodeSpendingSummary"},"summary":{"$ref":"#/definitions/OrderSummary"},"user":{"$ref":"#/definitions/User"},"payment_via":{"type":"string"},"payment_requested_at":{"type":["integer","null"]},"payment_transactions":{"type":"array","items":{"type":"string"},"description":"Blockchain TX hashes or processor IDs"},"payment_method_protocol":{"type":"string"},"payment_id":{"type":"string"},"payment_value":{"type":"string"},"campaign_rewards":{"type":["array","null"],"items":{"$ref":"#/definitions/CampaignReward"}},"state_transition_notification_url":{"type":["string","null"]},"sandbox_mode":{"type":["boolean","null"]},"store_type":{"type":["string","null"]},"is_payment_processor_external":{"type":"boolean"}},"required":["order_id","created_at","payment_state","order_state","is_payment_processor_external"],"additionalProperties":false},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"delivery_state":{"type":"string"},"kind":{"type":"string"},"deliverable":{"$ref":"#/definitions/ProductDeliverable"},"sandbox_mode":{"type":["boolean","null"]}},"required":["id","delivery_state","kind","deliverable"]},"ProductDeliverable":{"type":"object","properties":{"denomination":{"type":"string"},"localized_denomination":{"type":"string"},"family":{"type":"string"},"brand_name":{"type":"string"},"brand_logo":{"type":"string"},"brand_bg_color":{"type":"string"},"error_description":{"type":["string","null"]},"pin_code":{"oneOf":[{"type":"string","format":"uri","description":"URL the user must open to reveal / activate the code."},{"type":"string","pattern":"^[A-Za-z0-9-]{4,}$","description":"The gift-card code itself."}]},"pin_serial":{"type":["string","null"],"description":"Serial number (shown on some physical/virtual cards)."},"security_code":{"type":["string","null"],"description":"Extra security / CVV code if required by the brand."},"failure_reason":{"type":["string","null"]},"pin_usage_instructions":{"type":["string","null"],"description":"HTML instructions on how to redeem the code."},"barcode_image_url":{"type":["string","null"]},"qr_image_url":{"type":["string","null"]},"beneficiary_account":{"type":"string","description":"A string formatted as an email (if delivery_type requires email) or a phone number (if delivery_type requires phone).","oneOf":[{"format":"email","description":"Email format when delivery_type indicates email-based delivery."},{"pattern":"^\\+?[1-9]\\d{1,14}$","description":"Phone number format (E.164, up to 15 digits, optional leading +) when delivery_type indicates phone-based delivery."}]},"country_code":{"type":"string"},"delivery_type":{"type":"string"},"points":{"type":"string"},"coin_amount":{"type":"string"},"original_coin_amount":{"type":"string"},"original_price":{"type":"string"},"product_value":{"type":["string","null"]},"currency_code":{"type":["string","null"]},"redeem_instructions":{"type":["string","null"]},"terms_and_conditions":{"type":["string","null"]},"promotion":{"type":["object","null"]}},"required":["denomination","brand_name","beneficiary_account","country_code"]},"OrderSummary":{"type":"object","properties":{"coin_amount_before_discount":{"type":"string"},"coin_amount_after_discount":{"type":"string"},"coin_amount_to_pay_in_crypto":{"type":"string"},"coin_amount_to_pay_via_nft":{"type":"string"},"coin_amount_to_pay_via_coupon":{"type":"string"}},"required":["coin_amount_before_discount","coin_amount_after_discount","coin_amount_to_pay_in_crypto","coin_amount_to_pay_via_nft","coin_amount_to_pay_via_coupon"]},"PaymentFee":{"type":"object","additionalProperties":true},"Points":{"type":"object","additionalProperties":true},"NFTCodeSpendingSummary":{"type":"object","additionalProperties":true},"IEnrichedProblem":{"type":"object","additionalProperties":true},"CampaignReward":{"type":"object","properties":{"campaign_name":{"type":"string"},"campaign_description":{"type":"string"},"reward":{"type":"object","additionalProperties":true}},"required":["campaign_name","reward"]},"BaseCurrency":{"type":"object","properties":{"name":{"type":"string","examples":["BTC, ETH, USDT, USDC, SOL"]},"logo_url":{"type":"string"},"is_suspended":{"type":"boolean"}},"required":["name","logo_url","is_suspended"],"additionalProperties":false}},"analytics":{"track_events":["product_viewed","order_started","payment_initiated","order_completed"],"session_tracking":true}}