# AgentRefills

> The refill layer for AI agents. One API for an autonomous agent to buy gift cards, API credits, domains, cloud compute and eSIMs across 190+ countries, with per-agent spend caps, human approval, encrypted single-read codes, and a full audit trail. Available over MCP and REST.

AgentRefills gives an AI agent a wallet it can't misuse. An agent searches a catalog of thousands of products (5,000+ gift-card brands plus API credits, compute, domains and eSIMs), buys with a single idempotent call, and receives the code or credential once. Every purchase passes a fail-closed policy check, respects per-agent daily and monthly budgets, parks for human approval above a configurable threshold, and is fully traced and reconciled to a double-entry ledger.

Amounts are always integer minor units (cents). Errors use a closed taxonomy where every error carries an agent-actionable next step. Duplicate purchases are structurally impossible: re-using an idempotency key returns the existing order.

## The five agent tools

- list_brands (read-only, idempotent): Search purchasable products by query, country and category. Returns brand ids, denominations and stock.
- buy_giftcard (destructive, idempotent via client_ref): Start an async purchase. Returns a task id immediately. A repeated client_ref never buys twice.
- get_code (destructive, single release): Release the redemption code, link or PIN exactly once. A second call returns ALREADY_RELEASED.
- check_balance (read-only): The calling agent's remaining budget, daily and monthly limits, and kill-switch state.
- request_approval: Re-ping the human approver for a task parked in APPROVAL_REQUIRED. Rate-limited to one per task per hour.

## Safety and trust guarantees

- Fail-closed policy: if the policy engine is unreachable or undecided, the purchase is denied, never allowed.
- Per-agent spend caps: daily and monthly limits plus a brand allowlist, enforced on every purchase.
- Human-in-the-loop: purchases above your threshold are approved or rejected by a human in Slack before money moves.
- Encrypted single-read codes: codes are encrypted at rest, released once, access-logged, and never written to logs or traces.
- Zero duplicate payments: guaranteed by an idempotency key plus a unique payment-per-task constraint, not by chance.
- Full auditability: every order is reconstructable from an OpenTelemetry trace plus the ledger, with webhooks on completion.
- Sandbox-first: complete the entire flow against test products with zero real spend before going to production.

## What agents can buy

- Gift cards: Amazon, Apple, Steam, Walmart, Netflix, Uber, DoorDash, PlayStation, Xbox, Google Play and 5,000+ more brands.
- API credits: OpenAI, Anthropic, Perplexity.
- Cloud and GPU compute: AWS, Google Cloud, NVIDIA, Cloudflare, Vercel.
- Domains and web: Namecheap, GoDaddy.
- Messaging and payments credit, plus eSIMs and mobile top-ups.

## Works with

- MCP (Model Context Protocol): native MCP server usable by any MCP client, including Claude.
- Agent frameworks: OpenAI Agents SDK, LangChain, LangGraph, LlamaIndex, CrewAI, Vercel AI SDK.
- Plain REST: identical semantics to the MCP tools for any custom stack.

## Key pages

- [Home](https://agentrefills.com/): Product overview, the five tools, and the trust stack.
- [Agent purchasing docs](https://agentrefills.com/docs/): How an agent connects and buys, with per-SDK snippets.
- [Full agent guide (llms-full.txt)](https://agentrefills.com/llms-full.txt): Complete tool schemas, error taxonomy, and connection recipes in one file.
- [FAQ](https://agentrefills.com/#faq): Direct answers on spend limits, human approval, code security, sandbox and idempotency.
- [OpenAPI spec](https://agentrefills.com/openapi.yaml): Machine-readable REST contract mirroring the five tools.

## Framework guides

- [For Claude (MCP)](https://agentrefills.com/for/claude-mcp): Add the AgentRefills MCP server to Claude.
- [For the OpenAI Agents SDK](https://agentrefills.com/for/openai-agents-sdk): Wrap AgentRefills as a function tool.
- [For LangChain](https://agentrefills.com/for/langchain): Add a gift-card @tool to a LangChain or LangGraph agent.
- [For CrewAI](https://agentrefills.com/for/crewai): Give a CrewAI agent a gift-card tool.
- [For the Vercel AI SDK](https://agentrefills.com/for/vercel-ai-sdk): Define a typed tool that buys gift cards from the edge.

## Getting started

Request an API key, fund a balance, and set per-agent spend caps and an approval threshold. Point your agent at the MCP server or the REST endpoints, call buy_giftcard with an idempotency key, then get_code once the order completes. Start in the sandbox; flip to production when ready.