Skip to content
EthosEthosDevelopers

Agents and x402

Ethos reputation data is open. An agent can read it two ways:

  • Free, with a header. Every read endpoint under https://api.ethos.network/api/v2 answers any caller that sends X-Ethos-Client: <your-agent-name>. No key, no account. This is the whole API, documented on this site, and it is the way to go for anything beyond a one-off lookup. Vibe Coding Quickstart is written for an agent to read.
  • Paid per request, with x402. A handful of the most useful lookups are also served at https://developers.ethos.network/x402/… for $0.001 in USDC on Base per call, using the x402 protocol. These exist so the API is listed where agents look for tools (Coinbase’s x402 Bazaar, x402scan and other indexes only list resources that answer 402 Payment Required). An agent with an x402-capable client and a wallet needs no setup at all.

The data is identical. Pay only if your agent already pays for tools that way.

The x402 routes

Section titled “The x402 routes”
Route Returns Same as
GET /x402/score/{userkey} Credibility score and level GET /api/v2/score/userkey
GET /x402/user/x/{handle} The Ethos profile behind an X handle or account id GET /api/v2/user/by/x/{accountIdOrUsername}
GET /x402/user/address/{address} The Ethos profile behind an EVM address GET /api/v2/user/by/address/{address}
GET /x402/users/search?query=…&limit=… Profiles matching a name, handle or address fragment GET /api/v2/users/search
GET /x402/xp/{userkey} Total XP across all seasons GET /api/v2/xp/user/{userkey}

A userkey names a person any way Ethos knows them: address:0x…, profileId:1, service:x.com:username:ethos_network, service:x.com:<account id>, service:discord:<id> or service:telegram:<id>.

Machine-readable descriptions of the routes:

  • https://developers.ethos.network/.well-known/x402, the discovery document crawlers read.
  • https://developers.ethos.network/openapi.json, an OpenAPI 3.1 document for just these routes (also at /x402/openapi.json).

How a paid call works

Section titled “How a paid call works”
  1. Request the route with no payment. The answer is 402 Payment Required; its PAYMENT-REQUIRED header (and the JSON body) carry the price, the USDC contract on Base, the address to pay and, under extensions.bazaar, what the route takes and returns.
  2. Sign a USDC transfer for that amount (EIP-3009, so the payer needs no ETH for gas) and send the same request again with it in the PAYMENT-SIGNATURE header.
  3. The facilitator verifies and settles it on Base; the response is the lookup, with a PAYMENT-RESPONSE header carrying the transaction.

Any x402 client does all of this for you:

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


// A wallet holding a little USDC on Base (eip155:8453).
const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const client = registerExactEvmScheme(new x402Client(), { signer: account });
const fetchWithPay = wrapFetchWithPayment(fetch, client);


const res = await fetchWithPay(
  "https://developers.ethos.network/x402/score/service:x.com:username:ethos_network",
);
console.log(await res.json()); // { score: 2441, level: "revered" }
console.log(res.headers.get("PAYMENT-RESPONSE")); // the settlement, base64 JSON

Details

Section titled “Details”
  • Network and asset: USDC on Base mainnet (eip155:8453), exact scheme, $0.001 per request. The price is in the 402; do not hard-code it.
  • Facilitator: Coinbase’s CDP facilitator settles the payments. The payer pays no gas.
  • Rate limits and errors: the same as the free API, whose status codes and bodies are passed through unchanged. A rejected payment is a fresh 402 whose body says why (for example, not enough USDC in the wallet).
  • No API key is ever issued by the x402 routes, and they never write anything. For writes (reviews, vouches, XP tips) use API keys with the free API.