@sperax/tool-bitrefill

Buy gift cards, eSIMs, and 10,000+ digital products with crypto across 180+ countries via Bitrefill.

Bitrefill is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-bitrefill

Usage

Call it directly

import { bitrefillExecutor } from '@sperax/tool-bitrefill';

const result = await bitrefillExecutor.invoke('searchProducts', {"query":"<query>","country":"<country>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { BitrefillManifest, bitrefillExecutor } from '@sperax/tool-bitrefill';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: BitrefillManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await bitrefillExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

BitrefillManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-bitrefill

API reference

searchProducts

Search for gift cards, eSIMs, and other digital products on Bitrefill. Returns a JSON object with a "products" array containing product id, name, type, country, and priceRange.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | query | string | yes | Short search keyword, 1-3 words. Examples: "Amazon", "Netflix", "eSIM", "Uber Eats", "Steam". Do NOT use full sentences. | | country | string | no | ISO 3166-1 alpha-2 country code to filter results (e.g. "US", "DE", "JP"). | | category | string | no | Product category filter. Valid values include: "esim", "streaming", "games", "game-stores", "food", "food-delivery", "restaurants", "groceries", "phone-services", "phone", "refill", "data", "bundles", "retail", "amazon", "department-stores", "online-marketplaces", "entertainment", "music", "travel", "flights", "accommodation", "electronics", "home", "apparel", "health-beauty", "sports-n-outdoors", "gifts", "digital-wallet", "payment-cards", "vpn", "bill", "utility-bills", "education", "other". | | limit | number | no | Maximum number of results to return. Default: 10. |

productDetails

Get full details for a specific product including available denominations, pricing, supported countries, and redemption instructions.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The Bitrefill product ID (obtained from searchProducts). |

buyProducts

Create an invoice to purchase one or more products. Returns an invoice with payment instructions. Supports Bitcoin, Lightning, Ethereum, and various stablecoins (USDC/USDT on multiple chains).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | products | array | yes | Array of products to purchase. Each item needs a productId, optional value (denomination), and optional quantity. | | paymentMethod | string | no | Preferred payment method. Valid values: "bitcoin", "ethereum", "lightning", "usdc_polygon", "usdt_polygon", "usdc_erc20", "usdt_erc20", "usdc_arbitrum", "usdc_solana", "usdc_base", "eth_base". |

getInvoiceById

Check the status of an invoice by ID. Returns payment status, amount, and payment method details.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The invoice ID (returned from buyProducts). |

getOrderById

Get order details by ID including gift card codes, eSIM activation details, or other redemption information. Only available after payment is confirmed.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The order ID. |

listInvoices

List recent invoices for the authenticated account.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Maximum number of invoices to return. Default: 10. |

unsealOrder

Unseal an order to reveal redemption codes, gift card PINs, eSIM activation details, or other sensitive delivery information. Must be called after payment is confirmed.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The order ID to unseal. |

listOrders

List recent orders for the authenticated account.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Maximum number of orders to return. Default: 10. |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-bitrefill is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0