DEV Community

Cover image for Let your agent check invoices and IBANs in code, not in its head
bartelmost for AgentShield

Posted on Originally published at agentshield.live

Let your agent check invoices and IBANs in code, not in its head

An agent that pays an invoice or promises a delivery date usually does the arithmetic itself: net plus VAT, an IBAN checksum, "10 business days from now, minus Bavarian holidays". A language model can do that, but slowly, with reasoning tokens, and now and then wrong. A wrong IBAN or a forgotten public holiday costs more than the check.

agentshield.live is a set of pay-per-call HTTP checks for exactly that step. One call, one deterministic JSON answer with ok and a list of failed fields. It is paid per call in USDC on Base through x402. No account, no API key.

What an answer looks like

/invoice with a VAT amount that is one unit too high:

{
  "known": true,
  "ok": false,
  "net": "100.00", "vat": "20.00", "gross": "119.00",
  "rate_percent": 19, "expected_vat": "19.00",
  "failed": ["sum", "vat_amount"]
}
Enter fullscreen mode Exit fullscreen mode

That drops straight into if (!out.ok). The bundles are /transfer (0.02 USDC), /invoice (0.03), /deadline (0.01), /holidays (0.008) and /cryptopay (0.01). Single checks start at 0.001 USDC. The exact price is always the one in the live 402 response.

Three lines in Node

npm i agentshield-live
Enter fullscreen mode Exit fullscreen mode
import { createAgentShield } from "agentshield-live";

const shield = createAgentShield({
  maxUsdc: 0.05,                                   // hard per-call cap
  onPay: (p) => console.log(`[agentshield] ${p.route} ${p.price_usdc} USDC tx=${p.transaction}`),
});

const out = await shield.call("agentshield_invoice", { net: "100.00", vat: "20.00", gross: "119.00", country: "DE" });
Enter fullscreen mode Exit fullscreen mode

The key is your own wallet key (X402_PAYER_KEY). It never leaves your machine. onPay is optional and gives you one line per settled payment, so you see what the agent spends.

How x402 actually works

Many examples on the web get this wrong, so here it is plainly:
GET /iban?iban=DE89... answers 402 Payment Required with one header, PAYMENT-REQUIRED. It holds base64 JSON: amount, asset (USDC), network (eip155:8453), payTo.
The client signs an EIP-712 USDC transfer authorization (EIP-3009) for that amount. It is not a plain text message.
The same request goes again with PAYMENT-SIGNATURE. The answer is 200 plus PAYMENT-RESPONSE with the settlement.
Use an x402 client (@x402/fetch, or x402 in Python) instead of building that by hand.

Not paying for nonsense

Two things keep a confused agent from burning money:
Missing or unknown input returns 404 before any payment, with X-AgentShield-Retryable: false. Nothing is charged. The client should not sign it.
A free MCP tool, choose_route on https://agentshield.live/mcp, answers pay, compute or skip for one sentence. Simple arithmetic gets compute: do it locally.
For CI there is a dry run. It needs no key and never pays:

const shield = createAgentShield({ dryRun: true });   // or AGENTSHIELD_DRY_RUN=1
await shield.call("agentshield_invoice", { net: "100.00", gross: "119.00", country: "DE" });
// { dryRun: true, status: 402, charged: false, price_usdc: 0.03, would_pay: true, ... }
Enter fullscreen mode Exit fullscreen mode

It returns the live price, not a made-up check result. A real payment rehearsal runs on Base Sepolia: https://agentshield.live/try.md.

Measured numbers

  • A paid call took about 1.0 to 1.4 s end to end, including settlement (measured 2026-11-12, 3 calls each on /iban and /deadline, from one host).

  • An unpaid 402 came back in under 10 ms.

  • Token savings depend on your model. As a rough estimate, an IBAN check reasoned out step by step is 500 to 1,500 tokens. At 10 to 25 USD per million output tokens, that is about 0.005 to 0.04 USD, against 0.005 USDC for /iban.

What it is not

Not a firewall, not a security audit, not a certificate. It does not confirm that an account exists or that money is owed. Answers come from code and stored tables, not live market data.
Links: route list · llms.txt · integration guide · source (MIT)

Top comments (0)