Everything your AI agents need to buy.

# 1. create a purchase (sandbox: X-Agent-Id, or Bearer token in prod)
curl -X POST https://api.agentrefills.com/v1/purchases \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: agent_demo" \
  -d '{"brand_id":"amazon","amount_minor":2500,"currency":"USD"}'

# → {"task_id":"tsk_9F2A","status":"accepted","state":"completed"}

# 2. release the code once (from the vault)
curl -X POST https://api.agentrefills.com/v1/purchases/tsk_9F2A/code \
  -H "X-Agent-Id: agent_demo"

# → {"code":"GIFT-XXXX-9F2A","face_minor":2500,"remaining_minor":2500}

import time, requests

BASE = "https://api.agentrefills.com"
H = {"X-Agent-Id": "agent_demo"}

# create -> poll -> release
r = requests.post(f"{BASE}/v1/purchases", headers=H, json={
    "brand_id": "amazon", "amount_minor": 2500, "currency": "USD",
})
r.raise_for_status()
task = r.json()["task_id"]

while requests.get(f"{BASE}/v1/purchases/{task}", headers=H).json()["state"] != "completed":
    time.sleep(0.45)

code = requests.post(f"{BASE}/v1/purchases/{task}/code", headers=H).json()
print(code["code"], code["face_minor"])

const BASE = "https://api.agentrefills.com";
const H = { "Content-Type": "application/json", "X-Agent-Id": "agent_demo" };

// create -> poll -> release
let r = await fetch(`${BASE}/v1/purchases`, {
  method: "POST", headers: H,
  body: JSON.stringify({ brand_id: "amazon", amount_minor: 2500, currency: "USD" }),
});
if (!r.ok) throw await r.json();
const { task_id } = await r.json();

let state = "accepted";
while (state !== "completed") {
  await new Promise((res) => setTimeout(res, 450));
  state = (await (await fetch(`${BASE}/v1/purchases/${task_id}`, { headers: H })).json()).state;
}

const code = await (await fetch(`${BASE}/v1/purchases/${task_id}/code`, { method: "POST", headers: H })).json();
console.log(code.code, code.face_minor);

# AgentRefills posts order events to your endpoint.
# HMAC-verified (X-Signature) and deduped on (provider, event_id).

POST https://your-app.com/hooks/agentrefills
X-Signature: "t=1720224000,v1=<hmac-sha256>"

{
  "provider": "bitrefill",
  "event_id": "evt_7c1e",
  "type": "purchase.completed",
  "task_id": "tsk_9F2A",
  "brand_id": "amazon",
  "face_minor": 2500
}

# Verify the HMAC, then look up by event_id — a replay is a no-op.
# Endpoint: POST /v1/webhooks/bitrefill

{
  "tools": [
    { "name": "list_brands",      "annotations": { "readOnlyHint": true } },
    { "name": "buy_giftcard",     "annotations": { "destructiveHint": true, "idempotentHint": true },
      "input": {
        "brand_id":     "amazon",
        "amount_minor": 2500,
        "currency":     "USD",
        "client_ref":   "idem_2f9c"
      } },
    { "name": "get_code",         "annotations": { "readOnlyHint": false } },
    { "name": "check_balance",    "annotations": { "readOnlyHint": true } },
    { "name": "request_approval", "annotations": { "readOnlyHint": false } }
  ]
}