--- name: api.reloadpi.com description: ReloadPI (api.reloadpi.com) is a catalog and fulfillment API for three prepaid digital products: mobile top-ups, gift card/voucher codes, and eSIM data plans. It exposes endpoints to discover available offers, retrieve purchase workflow metadata, execute purchases via x402 USDC payments, and check order fulfillment status. host: api.reloadpi.com --- # api.reloadpi.com ReloadPI serves agents and applications that need to programmatically purchase prepaid mobile services globally. It covers three distinct product verticals — mobile airtime/bundle top-ups, gift cards and vouchers, and eSIM data plans — each with its own catalog browsing, purchase workflow, and (for eSIMs) order status tracking. Payments are handled via x402 USDC. The host does not provide real-time balance checks, number validation, or network availability verification. ## When to use this host Use api.reloadpi.com when an agent needs to purchase prepaid mobile top-ups, gift card vouchers, or eSIM data plans and pay via USDC through the x402 protocol. It is the right host when the agent must first discover valid countries, browse a product catalog, understand purchase schema, and then execute a buy. Do not use this host for real-time mobile network availability checks, phone number validation, or live balance queries — it has no skills for those. Do not use it for post-purchase order tracking of top-up or voucher orders; only eSIM orders have a status endpoint. If an agent needs fiat payment rails or non-USDC settlement, this host is not suitable. There are no alternative hosts hinted at within the skill set for these specific product verticals. ## Capabilities ### Geographic Discovery Returns the set of countries and regions supported across product verticals, enabling agents to validate eligibility before querying catalogs or initiating purchases. - **`fetch-topup-supported-countries`** — Returns the full list of ISO 3166-1 alpha-2 country codes supported by the ReloadPi top-up catalog. - **`fetch-topup-regions`** — Returns a JSON array of available geographic regions for top-up catalog services, such as Middle East and North Africa, Western Europe, and Southeast Asia. - **`fetch-voucher-supported-countries`** — Returns the list of ISO 3166-1 alpha-2 country codes for which vouchers are available in the ReloadPi catalog. ### Catalog Browsing Returns paginated offer listings with pricing, allowances, and offer IDs for each product type, enabling agents to present options to users or select an offer ID for downstream purchase flows. - **`fetch-topup-offers-catalog`** — Returns a paginated catalog of mobile top-up and bundle offers filtered by country and carrier, including pricing in USD, data/voice/SMS allowances, duration, and regional metadata. - **`fetch-voucher-offers-catalog`** — Returns a paginated list of voucher and gift card offers including offer IDs, brand names, country/region availability, sub-categories, pricing in USD, and product type. - **`fetch-esim-offers-catalog`** — Returns the full catalog of available eSIM plans including country, region, data allowance, duration, pricing, and speed tier subtype for each offer. ### Voucher Catalog Filtering Returns available filter dimensions (countries, regions, sub-types, brands) for the voucher catalog so agents can narrow searches before retrieving offer listings. - **`fetch-voucher-catalog-filters`** — Returns available filter options for the voucher catalog, including supported countries, sub-types, regions, and brand names. ### Purchase Workflow Metadata Returns the required request body schema, pricing model, payment mechanics, and fulfillment details for each product type before an agent constructs and submits a purchase call. - **`fetch-topup-purchase-info`** — Returns pricing, payment, and workflow details for executing a mobile topup purchase, including request body schema, price range, and fulfillment steps. - **`fetch-voucher-purchase-info`** — Returns the full purchase workflow, required request body schema, pricing model, fulfillment fields, and refund policy for catalog voucher purchases via POST /api/catalog/vouchers/purchase. - **`fetch-esim-purchase-info`** — Returns the purchase workflow, required POST body parameters, pricing range, and payment details needed to buy or top-up an eSIM plan via the ReloadPI catalog. ### Order Status and Fulfillment Returns the current fulfillment state, delivery payload (ICCID and QR code), and refund eligibility for a placed eSIM order by orderId. - **`fetch-esim-order-info`** — Returns fulfillment state, delivery payload (ICCID and QR code URL), refund eligibility, and polling semantics for a catalog eSIM order by orderId. ## Workflows ### Mobile Top-Up Purchase Flow *Use when an agent needs to recharge a mobile number — from validating the target country through selecting an offer to understanding how to submit the purchase.* 1. **`fetch-topup-supported-countries`** — Validate that the target country is supported before proceeding. 2. **`fetch-topup-regions`** — Optionally identify the geographic region for filtering or display purposes. 3. **`fetch-topup-offers-catalog`** — Retrieve available top-up and bundle offers for the target country and carrier, capturing the offerId. 4. **`fetch-topup-purchase-info`** — Retrieve the required POST body schema, USDC payment details, and fulfillment workflow before constructing the purchase request. ### Voucher Purchase Flow *Use when an agent needs to buy a gift card or voucher — from discovering valid filter values through selecting a brand offer to understanding the purchase mechanics.* 1. **`fetch-voucher-supported-countries`** — Confirm the target country is eligible for voucher purchase. 2. **`fetch-voucher-catalog-filters`** — Retrieve valid filter dimensions (regions, sub-types, brands) to narrow the catalog query. 3. **`fetch-voucher-offers-catalog`** — Browse available voucher and gift card offers, capturing the offerId and priceType for the selected product. 4. **`fetch-voucher-purchase-info`** — Retrieve the required POST body schema, FIXED vs RANGE pricing logic, and USDC payment details before submitting the purchase. ### eSIM Purchase and Delivery Flow *Use when an agent needs to provision an eSIM data plan — from browsing available plans through purchasing to polling for the ICCID and QR code.* 1. **`fetch-esim-offers-catalog`** — Browse available eSIM plans filtered by country, data size, duration, or speed tier to select an offerId. 2. **`fetch-esim-purchase-info`** — Retrieve the required POST body schema, pricing range, and USDC payment mechanics before constructing the purchase request. 3. **`fetch-esim-order-info`** — After purchase, poll with the returned orderId to retrieve fulfillment status, ICCID, QR code URL, and refund eligibility. ## Skill reference ### `fetch-topup-purchase-info` **Topup Purchase Info** — Returns pricing, payment, and workflow details for executing a mobile topup purchase, including request body schema, price range, and fulfillment steps. *Use when:* Use when an agent needs to understand how to construct and submit a topup purchase request, including required body parameters, USDC payment handling, price range, and the full order fulfillment workflow before calling POST /api/catalog/topups/purchase. *Not for:* Do not use to browse available topup offers or look up offer IDs — use GET /api/catalog/topups/offers for that. Do not use to check order status — use GET /api/catalog/orders/:orderId instead. **Returns:** Returns the purchase endpoint spec including body schema, USDC payment instructions, price range ($1–$50), a 4-step workflow, and the expected response shape with orderId and pollUrl. **Example:** `GET https://api.reloadpi.com/api/catalog/topups/purchase/info` --- ### `fetch-voucher-purchase-info` **Voucher Purchase Info** — Returns the full purchase workflow, required request body schema, pricing model, fulfillment fields, and refund policy for catalog voucher purchases via POST /api/catalog/vouchers/purchase. *Use when:* Use when an agent needs to understand how to purchase a catalog voucher — including required body parameters, how to handle x402 USDC payment, priceType logic (FIXED vs RANGE), recipient fields, and what the purchase response contains before executing a buy. *Not for:* Do not use to browse available voucher brands or offers; use GET /api/catalog/vouchers/offers for that. Do not use to actually execute a purchase — this endpoint only returns instructional metadata about the purchase flow. **Returns:** Returns a JSON object describing the purchase endpoint, required body params (offerId, recipient, optional value), x402 USDC payment instructions, FIXED/RANGE priceType logic, a 3-step workflow, the expected purchase response shape, and a no-refund policy. **Example:** `GET https://api.reloadpi.com/api/catalog/vouchers/purchase/info` --- ### `fetch-esim-order-info` **eSIM Order Info** — Returns fulfillment state, delivery payload (ICCID and QR code URL), refund eligibility, and polling semantics for a catalog eSIM order by orderId. *Use when:* Use when an agent needs to check the current fulfillment status of a previously placed eSIM order, retrieve the ICCID or QR code for delivery, or determine refund eligibility after a purchase. *Not for:* Do not use to place a new eSIM order or to look up top-up/voucher orders; refund eligibility and policies differ by product type and this endpoint is specific to eSIM catalog orders. **Inputs:** - `orderId` (string, required) — UUID of the eSIM order returned from a prior purchase call. Used to poll fulfillment state and retrieve delivery payload. **Returns:** Returns an order object with status (e.g. FULFILLED), delivery payload containing ICCID and QR code URL, refund eligibility flag, refund policy, and poll_again flag indicating whether further polling is needed. **Example:** `GET https://api.reloadpi.com/api/catalog/esims/orders/info?orderId=550e8400-e29b-41d4-a716-446655440000` --- ### `fetch-esim-purchase-info` **eSIM Purchase Info** — Returns the purchase workflow, required POST body parameters, pricing range, and payment details needed to buy or top-up an eSIM plan via the ReloadPI catalog. *Use when:* Use when an agent needs to understand the checkout flow, required inputs, and payment mechanics before calling POST /api/catalog/esims/purchase to buy or recharge an eSIM. *Not for:* Do not use to actually execute an eSIM purchase; use POST /api/catalog/esims/purchase for that. Not suitable for browsing available plans — use GET /api/catalog/esims/offers instead. **Returns:** Returns the purchase endpoint path, HTTP method, content type, x402 USDC payment instructions, price range ($1.75–$111), required body parameters, a 3-step workflow, and the expected purchase response shape including orderId, iccid, and QR code fields. **Example:** `GET https://api.reloadpi.com/api/catalog/esims/purchase/info` --- ### `fetch-topup-regions` **Topup Regions Finder** — Returns a JSON array of available geographic regions for top-up catalog services, such as Middle East and North Africa, Western Europe, and Southeast Asia. *Use when:* Use when an agent needs to enumerate valid region names before querying or filtering a top-up catalog, or when presenting region options to a user for selection. *Not for:* Do not use to retrieve actual top-up products or pricing; use a catalog or product listing endpoint instead. **Returns:** Returns a flat JSON array of 12 region name strings covering all geographic areas supported by the top-up catalog. **Example:** `GET https://api.reloadpi.com/api/catalog/topups/regions` --- ### `fetch-voucher-catalog-filters` **Voucher Filter Catalog** — Returns available filter options for the voucher catalog, including supported countries, sub-types, regions, and brand names. *Use when:* Use when an agent needs to discover valid filter values (countries, regions, sub-types, or brands) before querying or displaying the voucher catalog to a user. *Not for:* Do not use to retrieve actual voucher listings or pricing; use a voucher search or catalog endpoint instead. **Returns:** Returns a JSON object with four arrays: countries (ISO codes), subTypes (category labels), regions (geographic groupings), and brands (brand name strings). **Example:** `GET https://api.reloadpi.com/api/catalog/vouchers/filters` --- ### `fetch-voucher-supported-countries` **ReloadPi Voucher Countries** — Returns the list of ISO 3166-1 alpha-2 country codes for which vouchers are available in the ReloadPi catalog. *Use when:* Use when an agent needs to validate whether a specific country is eligible for voucher purchase or redemption before proceeding with a catalog lookup or order. *Not for:* Do not use to retrieve available voucher products or denominations for a country; use a catalog products endpoint instead. **Returns:** Returns a JSON array of objects each containing a 'code' field with an ISO 3166-1 alpha-2 country code, covering 56 supported countries such as US, GB, DE, and NG. **Example:** `GET https://api.reloadpi.com/api/catalog/vouchers/countries` --- ### `fetch-voucher-offers-catalog` **Voucher Offers Catalog** — Returns a paginated list of voucher and gift card offers including offer IDs, brand names, country/region availability, sub-categories, pricing in USD, and product type. *Use when:* Use when an agent needs to browse or search available voucher and gift card products, retrieve offer IDs for downstream purchase flows, or display brand/pricing metadata to a user selecting a gift card. *Not for:* Do not use to redeem or purchase a voucher; this endpoint only lists available offers. Not suitable for real-time price feeds or single-offer lookups by ID. **Returns:** Returns a list array of voucher offer objects, each with offerId, brand, brandName, image URL, country, regions, subTypes, a price object (fixed face value in minor currency units, margin, fee), priceType, and productType. **Example:** `GET https://api.reloadpi.com/api/catalog/vouchers/offers` --- ### `fetch-topup-supported-countries` **ReloadPi Topup Countries** — Returns the full list of ISO 3166-1 alpha-2 country codes supported by the ReloadPi top-up catalog. *Use when:* Use when an agent needs to validate whether a specific country is eligible for a top-up request, or to enumerate all countries available in the ReloadPi catalog before initiating a top-up flow. *Not for:* Do not use to retrieve available top-up products or operators for a country; use a catalog products endpoint instead. Not suitable for real-time operator availability checks. **Returns:** Returns a JSON array of objects each containing a 'code' field with an ISO 3166-1 alpha-2 country code; the real response includes 113 supported countries such as US, NG, IN, BR, and ZA. **Example:** `GET https://api.reloadpi.com/api/catalog/topups/countries` --- ### `fetch-topup-offers-catalog` **ReloadPi Topup Offers Catalog** — Returns a paginated catalog of mobile top-up and bundle offers filtered by country and carrier, including pricing in USD, data/voice/SMS allowances, duration, and regional metadata. *Use when:* Use when an agent needs to browse or search available mobile top-up or bundle offers for a specific country or carrier, including pricing details and allowance specifications before initiating a recharge. *Not for:* Do not use to execute or place a top-up order; this endpoint only retrieves the catalog of available offers. Not suitable for real-time balance checks or number validation. **Returns:** Returns a list array of offer objects each containing offerId, brand, country, pricing in USD cents, data/voice/SMS allowances, duration in days, regions, and subTypes. **Example:** `GET https://api.reloadpi.com/api/catalog/topups/offers` --- ### `fetch-esim-offers-catalog` **ReloadPi eSIM Offers Catalog** — Returns the full catalog of available eSIM plans including country, region, data allowance, duration, pricing, and speed tier subtype for each offer. *Use when:* Use when an agent needs to browse or filter available eSIM plans by country, data size, duration, or speed tier before presenting options to a user or initiating a purchase. *Not for:* Do not use to purchase or activate an eSIM; this endpoint only returns catalog listings. Not suitable for real-time network availability checks. **Returns:** Returns a list array of eSIM offer objects, each with offerId, country, regions, dataGB, dataUnlimited, durationDays, price (integer cents), priceCurrency, subTypes speed tier, and usage notes. **Example:** `GET https://api.reloadpi.com/api/catalog/esims/offers` ---