Address validation your AI agent can pay for on its own.

In three calls

The same service as over HTTP, plugged into the protocol your agent already speaks.

1. Discover, for free

   The /.well-known/mcp-server card describes the server. initialize then tools/list on /mcp cost nothing.

2. Get the offer

   A tools/call without payment returns an error tool result (isError) whose content is the exact x402 v2 offer: network, USDC token, amount (20000 units, that is 0.02 USDC), destination.

3. Pay, then receive

   The agent signs the authorization (EIP-3009) and sends the call again with the payment in params._meta["x402/payment"] (or the X-PAYMENT header of a v1 client). The result arrives after settlement, with its receipt.

MCP client configuration

{
  "mcpServers": {
    "address-validator": { "url": "https://kder-ai.com/mcp" }
  }
}

Calling the tool

POST https://kder-ai.com/mcp
{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "validate_address",
    "arguments": { "address": {
      "street": "1600 Amphitheatre Parkway", "city": "Mountain View",
      "state": "CA", "zip": "94043", "country": "US" } }
  }
}

The offer read in the tool result

"accepts": [{
  "scheme": "exact", "network": "eip155:8453",
  "amount": "20000",
  "asset": "USDC", "payTo": "0x…"
}]

Pay from your code

The official x402 libraries read the offer, sign and pay on their own, in x402 v1 and v2 alike. Set a spending cap, then call the API like any other.

Python · x402 + httpx

# pip install "x402[httpx,evm]"
import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client().set_spend_controls({"max_amount_per_payment": "$0.05"})
    signer = EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"]))
    register_exact_evm_client(client, signer)
    async with x402HttpxClient(client) as http:
        response = await http.post("https://kder-ai.com/validate", json={"address": {
            "street": "1600 Amphitheatre Parkway", "city": "Mountain View",
            "state": "CA", "zip": "94043", "country": "US"}})
        await response.aread()
        print(response.status_code, response.json())

asyncio.run(main())

JavaScript · @x402/fetch

// npm install @x402/fetch @x402/evm viem, then run as an ES module (pay.mjs)
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
client.setSpendControls({ maxAmountPerPayment: "$0.05" });
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.EVM_PRIVATE_KEY)));

const pay = wrapFetchWithPayment(fetch, client);
const response = await pay("https://kder-ai.com/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: {
    street: "1600 Amphitheatre Parkway", city: "Mountain View",
    state: "CA", zip: "94043", country: "US" } }),
});
console.log(response.status, await response.json());

What the agent receives

A JSON answer, always the same shape.

• validatedwhether the address is recognised
• standardizedline1, line2, city, state, zip, country
• latitude · longitudethe GPS coordinates of the address
• deliverabilityresidential, commercial…
• confidencea confidence score from 0 to 1
• degradedtrue: the provider did not answer, try again

Why x402 for an agent

No account to create, no key to store, no subscription: the agent pays exactly for what it uses, when it uses it. An authorization already used is refused: the same payment never counts twice.

Good to know

• The United States are checked with USPS (DPV), France and overseas territories with the Base Adresse Nationale; elsewhere, verification remains partial.
• degraded set to true means the provider did not answer: it is not a wrong address, call again later.
• No more than 10 requests per second per IP address.
• The address is not kept in the logs; the result stays 30 days in cache so we can answer faster.
• A shop without a wallet uses the same service with an API key and a subscription.

Frequently asked questions

Integration guide Pricing Price comparison