# Cryptorefills API

> Buy gift cards, top up mobile phones, and purchase travel eSIMs with cryptocurrency. 10,500+ brands across 180+ countries. No account, OAuth, or API key required for MCP or x402 flows.

Cryptorefills is a cryptocurrency-powered marketplace for digital goods. Users and AI agents pay with Bitcoin, Lightning, Ethereum, Solana, USDC, USDT, and 15+ other cryptocurrencies across Base, Polygon, Arbitrum, Tron, TON, SUI, and more networks.

The API is agent-native: autonomous purchasing via the Model Context Protocol (MCP) or the x402 HTTP payment protocol works without any account or credential provisioning.

## Discovery

- [API catalog (this endpoint's parent, RFC 9727)](https://api.cryptorefills.com/.well-known/api-catalog)
- [MCP manifest (machine-readable service description)](https://api.cryptorefills.com/.well-known/mcp.json)
- [Agent Skills index (RFC v0.2.0)](https://api.cryptorefills.com/.well-known/agent-skills/index.json)
- [Health / liveness probe](https://api.cryptorefills.com/healthz)

## Published Agent Skills

- [cryptorefills-buy](https://api.cryptorefills.com/.well-known/agent-skills/cryptorefills-buy/SKILL.md) — full MCP purchase workflow (search, price, order, pay, track)
- [cryptorefills-catalog](https://api.cryptorefills.com/.well-known/agent-skills/cryptorefills-catalog/SKILL.md) — read-only product discovery (brands, countries, categories)
- [cryptorefills-x402](https://api.cryptorefills.com/.well-known/agent-skills/cryptorefills-x402/SKILL.md) — autonomous agent commerce via x402 HTTP 402 + USDC on Base

## MCP Transports

- HTTP streaming: `POST https://api.cryptorefills.com/mcp/http`
- Server-Sent Events: `GET` or `POST https://api.cryptorefills.com/mcp/sse`
- Required header: `User-Agent: Cryptorefills-MCP/1.0`

## Selected REST Endpoints (Public, Unauthenticated)

- `GET /v5/products/country/:country_code` — list products purchasable in a country
- `GET /v5/products` — search products by brand or product family
- `GET /v2/brands` — list all brands
- `GET /v2/products/categories` — product category taxonomy
- `GET /homepage` — curated homepage sections
- `GET /healthz` — liveness probe

Versioned endpoints coexist (`/v2`, `/v3`, `/v4`, `/v5`, `/v6`). Prefer the highest version exposed for any given resource.

## Payment Models

- Standard crypto invoice: BTC, LTC, ETH, USDT, USDC, SOL, TON, SUI, TRX, XRP, MATIC, and more. Customer pays to a per-order address; we sweep on-chain.
- Bitcoin Lightning: instant, low-fee BTC payments via the Lightning Network (BTCPay Server).
- x402: HTTP 402 Payment Required protocol for autonomous AI-agent commerce. USDC on Base (chain 8453) using EIP-3009 `transferWithAuthorization`. No account, no OAuth.

## Source and Support

- Homepage: https://www.cryptorefills.com
- Agent skills source (canonical): https://github.com/Cryptorefills/agents
- This file is served under RFC 9727 `service-doc` from `/.well-known/api-catalog`.