Duo Data Utilities: IBAN, ISIN, VAT and Tax ID, Barcode, Timezone, Geo APIs

IBAN, ISIN, VAT/tax ID and GTIN barcode validation plus 29 more utilities for AI agents. Pay per call ($0.05 USDC on Base via x402), no API key, no signup.

Timezone and DST, geo distance and geohash, hashes and JWT decoding, airport, country, currency and NUTS lookups, money split, base conversion and more. Every call is one HTTP GET, paid per request.

Install

npm install duo-data-utilities viem

viem creates the wallet account that pays. This package also depends on it. Node.js 20 or later.

Python (not on PyPI, install from GitHub):

pip install "git+https://github.com/hiesem/duo-data-utilities#subdirectory=python"

Quick start

import { privateKeyToAccount } from "viem/accounts";
import { createClient } from "duo-data-utilities";

// Your wallet holds USDC on Base. Read the key from the environment, never a literal.
const client = createClient({ account: privateKeyToAccount(process.env.DUO_PAYER_KEY as `0x${string}`) });

const iban = await client.iban.validate({ iban: "NL91 ABNA 0417 1643 00" }); // $0.05
console.log(iban.valid, iban.country); // true NL

Counterparty check

checkCounterparty runs three checks in one call: IBAN (/v1/id/iban), tax ID (/v1/id/national) and country (/v1/ref/country). It costs $0.15.

const check = await client.checkCounterparty({
  iban: "NL91 ABNA 0417 1643 00",
  country: "NL",
  taxIdType: "bsn",
  taxId: "111222333",
});
console.log(check.verdict, check.reasons); // "pass", "fail" or "review"

• fail: the IBAN or the tax ID fails its checksum, the country is not an ISO 3166-1 country, or the API rejects an input as malformed.
• review: the IBAN country differs from the tax ID country, or the API does not cover that country or tax ID kind.
• pass: every check passed.

Structure and checksum only. The check does not query a company register, a bank or a tax authority, and it does not confirm that an account exists. UK is read as GB.

Methods

Every method costs $0.05 per call. Each method's JSDoc gives the route and the parameters. client.call(path, params) calls any route, and client.callWithReceipt(path, params) also returns the settlement receipt.

MCP

The MCP server is at https://api.duoleads.com/mcp (Streamable HTTP). tools/list is free. Each tools/call costs $0.05 and needs an x402-capable client or wallet bridge. See mcp/README.md for Claude Code, Claude Desktop, Cursor, VS Code and AgentCash.

Python

Python 3.10 or later. The client is typed (py.typed) and uses requests with x402's EVM signer. Routes and method names match the TypeScript client, in snake_case.

import os

from eth_account import Account
from duo_data_utilities import DuoClient

client = DuoClient(Account.from_key(os.environ["DUO_PAYER_KEY"]))  # your wallet, never a literal key
print(client.iban.validate(iban="NL91 ABNA 0417 1643 00")["valid"])

check = client.check_counterparty(iban="NL91 ABNA 0417 1643 00", country="NL", tax_id_type="bsn", tax_id="111222333")
print(check.verdict, check.reasons)

DuoClient(account, *, max_price_usd=0.05, timeout=None, pay_to=<service address>) applies the same price guard. Pass session= with a requests.Session that already pays to skip the guard. from_ is the Python name for the from query parameter.

Pricing and the price guard

• Every route costs $0.05 per call, paid in USDC on Base (eip155:8453) with x402 v2.
• maxPriceUsd defaults to 0.05. Before anything is signed, the client refuses a payment requirement that asks for more than that, a network other than Base, an asset other than Base USDC, or another payee. A refused call makes no payment and throws PriceGuardError.
• The client only signs payments to the service's public address 0xCD673f7e1daD254347AEab6be0DEFe8b9C6b3A39 (payTo option; pay_to in Python). Set it if you point baseUrl at another deployment.
• The client never retries a paid call on its own.
• Plain http:// is refused except for loopback addresses (localhost, 127.0.0.1, [::1]).
• With fetch instead of account, you pass a fetch that already pays. The price guard cannot check payments made inside it, so use account to keep the guard.

Examples

Runnable agents in examples/. Each folder has a README with setup, environment variables and cost.

Every call costs $0.05 in USDC on Base, paid by the wallet you configure. The examples' tests run offline with mocked responses; nothing in CI pays.

User-Agent and privacy

The SDK sends a User-Agent naming the SDK and version; the API stores only a coarse client class, see https://api.duoleads.com/privacy

• TypeScript: duo-data-utilities-js/<version> (+https://github.com/hiesem/duo-data-utilities). Override it with createClient({ userAgent }), or append your own product: userAgent: `${SDK_USER_AGENT} my-agent/1.0`.
• Python: duo-data-utilities-py/<version> (+https://github.com/hiesem/duo-data-utilities). Override it with DuoClient(..., user_agent=...), or append to duo_data_utilities.USER_AGENT.
• In browsers a page cannot set User-Agent, so the client sends none there, and it adds no other header in its place (one would make the browser send a CORS preflight, which the API does not accept). The browser's own User-Agent is sent instead.

What this is not

• Not a registry lookup. IBAN, tax ID and VAT checks are structure and checksum only.
• Not financial, legal or tax advice. Each response carries a disclaimer.

Links

• API docs: https://api.duoleads.com/docs
• OpenAPI: https://api.duoleads.com/openapi.json
• Machine-readable index: https://api.duoleads.com/llms.txt
• Terms: https://api.duoleads.com/terms
• Privacy: https://api.duoleads.com/privacy

The HTTP routes also work without this SDK. An unpaid GET returns 402 Payment Required with a PAYMENT-REQUIRED header, and any x402 v2 client can pay that challenge.

Development

npm install
npm run generate        # rebuild src/generated.ts from spec/ (npm test checks it is current)
npm run typecheck
npm test
npm run build

spec/ holds the snapshots the code is generated from. See spec/README.md.

License

MIT. See LICENSE.