Token reports for AI agents

What you need

• A wallet with its own private key (an EOA) holding USDC on Arc, 0.01 for each report. It needs nothing else, because Circle pays the gas. Smart-contract wallets are not supported yet.
• A token's address. Any token on Archipelago's radar can be reported on. A token it does not track, or one without a priced pool, is turned away before any charge.

To fund the wallet, send it USDC on Arc: withdraw from an exchange on the Arc network, or bridge from another chain, for example with Relay. The FAQ covers both routes. Give the agent a wallet of its own and keep in it only what the agent will spend, since its key sits with the agent.

TypeScript

With x402's own client for fetch, which answers the 402 and signs the payment for you:

npm install @x402/fetch @x402/core @x402/evm viem

import { wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const token = "0x3945DF1f8dD8F753FB62e428f3AaEB2c185a6E26"; // $ISLE
const res = await fetchWithPayment(`https://idx.archipelagodex.xyz/x402/report/${token}`);
const result = await new x402HTTPClient(client).processResponse(res);
console.log(res.status, result.body); // 200 and the report, or why not (nothing was charged)
if (res.ok) console.log("paid in", result.header.transaction);

Python

With x402's Python client, on 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

TOKEN = "0x3945DF1f8dD8F753FB62e428f3AaEB2c185a6E26"  # $ISLE

async def main():
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))
    async with x402HttpxClient(client) as http:
        r = await http.get(f"https://idx.archipelagodex.xyz/x402/report/{TOKEN}")
        await r.aread()
        print(r.status_code, r.json())  # 200 and the report, or why not (nothing was charged)

asyncio.run(main())

Both were tried against this endpoint with @x402/fetch 2.28 and x402 2.25 for Python. x402's buyer quickstart has clients for Go and Axios as well.

How the payment works

A client library does all of this; it is here for anyone writing their own.

1. The agent requests GET https://idx.archipelagodex.xyz/x402/report/<token address>. With no payment attached, the answer is 402 Payment Required, with the terms in a PAYMENT-REQUIRED header (base64-encoded JSON) and in the body. The terms, in its accepts list:

{
  "scheme": "exact",
  "network": "eip155:5042",
  "amount": "10000",
  "asset": "0x3600000000000000000000000000000000000000",
  "payTo": "0xDcf7a2683aCaaC06E85a50c15BAf59c8E8b1e681",
  "maxTimeoutSeconds": 120,
  "extra": { "name": "USDC", "version": "2", "assetTransferMethod": "eip3009" }
}

That is 10000 units of USDC on Arc (6 decimals, so 0.01 USDC), paid to Archipelago's treasury Safe.

2. The agent signs an EIP-3009 TransferWithAuthorization for exactly that amount to payTo, under USDC's EIP-712 domain (name USDC, version 2, chain 5042, the asset's address), and sends the request again with a PAYMENT-SIGNATURE header: base64-encoded JSON with x402Version 2, the terms it accepted, and the signed authorization. The authorization must be valid already, stay valid for at least 15 more seconds, and expire within 600 seconds. x402 clients sign it for 120.
3. Archipelago checks the terms and the signature, builds the report, and has Circle's Facilitator Service settle the transfer on Arc. Once Circle confirms it, the answer is 200 with the report as JSON, and a PAYMENT-RESPONSE header (base64-encoded JSON) holding the receipt: success, transaction (its hash on Arc), network, payer and amount.

The route allows cross-origin requests and exposes both payment headers, so an agent in a browser can use it too. Its OpenAPI description, for tools and directories that read one, is at https://idx.archipelagodex.xyz/openapi.json.

What a report holds

One JSON object, read from Arc and from Archipelago's own index of its trades. It states facts, not a rating.

Transfer taxes and sell blocks cannot be detected from contract code, and mint and pause mean only those standard functions. Contract facts are reused for up to 10 minutes.

When you are charged

• Only for a report you get. A token Archipelago cannot report on is answered 404, and while the index refills after a restart the answer is 503, both before any charge. The report goes out only once Circle confirms the transfer.
• Never twice for one request. The same PAYMENT-SIGNATURE sent again gets the same report and receipt, up to 3 answers while its authorization is valid. If a client signs a fresh payment for the same token while its last paid one is still valid, it is answered on that one, free.
• A payment that could not be confirmed yet is answered 503, asking for the same PAYMENT-SIGNATURE again. It is settled at most once, and no other payment from that wallet for that token is taken until it resolves.
• One authorization buys one report. Sent for another token, it is refused.

Answers and errors

Where the money goes

Every payment goes to Archipelago's treasury Safe, 0xDcf7a2683aCaaC06E85a50c15BAf59c8E8b1e681 on Arc, and shows on the Treasury page as a paid report. Half of the revenue from paid reports is set aside to buy and burn $ISLE as the treasury grows. That is a policy, not a contract; the whitepaper has the details.

More on the protocol: x402's documentation and Circle's Facilitator Service.