Agent Verifier Tutorials

Check & hold before you fulfill

One call: validates the budget, enforces every constraint, and reserves the amount so a parallel purchase can't overspend. idempotency_key makes retries safe (your order id works well).

curl -X POST https://verifier.goodmeta.co/v1/check -H "Authorization: Bearer gm_test_MERCHANT_KEY" -H "Content-Type: application/json" -d '{
  "budget_id": "pe_3f9a2b8c1d0e4f567890",
  "amount_cents": 2500,
  "vendor": "merchant_abc",
  "idempotency_key": "order-1001"
}'

{ "approved": true, "hold_id": "ver_a1b2c3d4e5f6g7h8i9j0", "remaining_cents": 47500 }

{ "approved": false, "reason": "BUDGET_EXCEEDED" }

Charge on your rail

The verifier authorizes — it doesn't move money. Charge with whatever you already use (Stripe, x402, bank, card). The hold guarantees the budget is reserved while you do.

Settle on success — or release on failure

Settle confirms the spend and debits the budget permanently. Release returns the unspent hold if the payment didn't go through.

curl -X POST https://verifier.goodmeta.co/v1/settle -H "Authorization: Bearer gm_test_MERCHANT_KEY" -H "Content-Type: application/json" -d '{ "hold_id": "ver_a1b2c3d4e5f6g7h8i9j0", "success": true }'

curl -X POST https://verifier.goodmeta.co/v1/release -H "Authorization: Bearer gm_test_MERCHANT_KEY" -H "Content-Type: application/json" -d '{ "hold_id": "ver_a1b2c3d4e5f6g7h8i9j0" }'

Refund a settled payment (later)

Reverse a committed charge, fully or partially. Restores the budget. The idempotency_key is required so a retry never double-refunds.

curl -X POST https://verifier.goodmeta.co/v1/refund -H "Authorization: Bearer gm_test_MERCHANT_KEY" -H "Content-Type: application/json" -d '{
  "hold_id": "ver_a1b2c3d4e5f6g7h8i9j0",
  "amount_cents": 2500,
  "idempotency_key": "refund-1001"
}'

Receive a budget id

The budget owner creates an envelope and gives your agent its id (e.g. pe_3f9a2b8c1d0e4f567890). Store it; reference it on every purchase.

Before each purchase, check the budget

Same /v1/check the merchant uses. If approved, you hold the budget and get a hold_id. If denied, stop — don't pay.

// pseudo-code around any purchase your agent makes
const res = await fetch("https://verifier.goodmeta.co/v1/check", {
  method: "POST",
  headers: { "Authorization": "Bearer gm_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    budget_id: budgetId,
    amount_cents: price,
    vendor: merchantId,
    idempotency_key: orderId,
  }),
}).then(r => r.json());

if (!res.approved) throw new Error("over budget: " + res.reason);
const holdId = res.hold_id;

Pay, then settle (or release)

Run your payment, then confirm the hold. On any failure, release it so the budget isn't consumed.

try {
  await payTheMerchant(price);          // your rail
  await fetch("https://verifier.goodmeta.co/v1/settle", {
    method: "POST",
    headers: { "Authorization": "Bearer gm_test_YOUR_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ hold_id: holdId, success: true }),
  });
} catch (e) {
  await fetch("https://verifier.goodmeta.co/v1/release", {
    method: "POST",
    headers: { "Authorization": "Bearer gm_test_YOUR_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ hold_id: holdId }),
  });
}

Connect the MCP endpoint

Point your MCP client at https://verifier.goodmeta.co/mcp and pass your key as a bearer header.

{
  "mcpServers": {
    "agent-verifier": {
      "url": "https://verifier.goodmeta.co/mcp",
      "headers": { "Authorization": "Bearer gm_test_YOUR_KEY" }
    }
  }
}

The tools the model can call

How a run looks

The model strings the tools together on its own:

You:   "Set a $50 budget for today, then buy the $12 API plan from Acme."
Agent: create_budget(amount_dollars=50, valid_hours=24)
        -> Budget pe_… created, $50.00
       check_budget(budget_id=pe_…, amount_cents=1200, vendor="acme")
        -> Approved. Hold ver_…, remaining $38.00
       (pays Acme)
       settle(hold_id=ver_…, success=true)
        -> Hold confirmed.