Build on x402Pulse

curl -i "https://www.x402pulse.dev/v1/top-traders?period=month"

Payments are in USDC on Base (eip155:8453). You only pay for successful responses: any error is never charged.

How it works

What happens, step by step, every time your agent calls x402Pulse.

1. Checks

   Your request arrives. Bad parameters get a free 400, and more than 60 calls a minute gets a free 429. You're never asked to pay for a request that can't succeed.

2. Price

   With no payment attached, x402Pulse answers 402 Payment Required. The PAYMENT-REQUIRED header says how much, in which token, on which network, and to which address.

3. Verify

   Your client signs a USDC authorization and resends the request. x402Pulse asks its facilitator (Coinbase) to confirm the signature, amount and network are valid. No money moves yet.

4. Answer

   x402Pulse builds the answer from Polymarket's public APIs (trades, leaderboards, positions, holders, markets), scores the wallets involved, and reuses recent results from its cache.

5. Settle

   Only if the answer succeeded, the facilitator settles the payment on the blockchain: USDC moves from your wallet to x402Pulse. If anything failed, it never settles.

6. Receive

   You get JSON with the data, plus a PAYMENT-RESPONSE header containing the receipt and transaction hash.

1. Check Node.js

   You need Node.js 20 or newer. Run this; it should print v20 or higher. If not, install it from nodejs.org.

   node -v

2. Create a project

   mkdir my-pulse-agent && cd my-pulse-agent
   npm init -y
   npm pkg set type=module
   npm install @x402/fetch @x402/evm viem

3. Create a test wallet

   This makes a brand-new wallet just for your agent and prints its private key and address.

   node -e "import('viem/accounts').then(({generatePrivateKey,privateKeyToAccount})=>{const k=generatePrivateKey();console.log('private key:',k);console.log('address:    ',privateKeyToAccount(k).address)})"

   Save the private key somewhere safe and never share it or paste it into chats, screenshots or GitHub. Anyone with it can spend the wallet's money. Use this wallet only for your agent, with small amounts.

4. Add a little USDC

   Send a few dollars of USDC on Base to the address from step 3. Check the network says Base before sending. You don't need any ETH.

5. Create the agent

   Create a file named agent.mjs in the folder, paste this in, and save it.

   import { x402Client, wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
   import { registerExactEvmScheme } from "@x402/evm/exact/client";
   import { privateKeyToAccount } from "viem/accounts";
   
   const API = "https://www.x402pulse.dev";
   const MAX_PRICE = 0.5; // never pay more than $0.50 for one call
   
   // 1. Load the wallet from the AGENT_KEY setting (never write the key in this file).
   const account = privateKeyToAccount(process.env.AGENT_KEY);
   const client = new x402Client();
   registerExactEvmScheme(client, { signer: account });
   
   // 2. A guardrail: see each price and refuse anything above MAX_PRICE.
   client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
     const price = Number(selectedRequirements.amount) / 1e6;
     console.log("Price:", price, "USDC");
     if (price > MAX_PRICE) return { abort: true, reason: "Too expensive" };
   });
   
   // 3. A fetch that pays automatically when it receives a 402.
   const pay = wrapFetchWithPayment(fetch, client);
   
   // 4. Ask who the most skilled traders are this month.
   const res = await pay(API + "/v1/top-traders?period=month&limit=5");
   console.log("Status:", res.status);
   const body = await res.json();
   
   if (res.ok) {
     for (const t of body.data.traders) {
       console.log(`#${t.rank} ${t.name ?? t.wallet}  skill ${t.skill} (${t.label})  edge ${Math.round(t.edge * 100)} pts`);
     }
     const receipt = new x402HTTPClient(client).getPaymentSettleResponse((h) => res.headers.get(h));
     console.log("Paid. Transaction:", receipt?.transaction);
   } else if (res.status === 402) {
     console.log("Not charged: the payment wasn't accepted. Check the wallet has USDC on the network shown in the 402 response.");
   } else {
     console.log("Not charged. Error:", body.error);
   }

6. Run it

   Replace the key with your private key from step 3. Putting it in front of the command keeps it out of your files.

   AGENT_KEY=0xYOUR_PRIVATE_KEY node agent.mjs

7. Read the result

   You should see something like this. The first run can take up to 30 seconds while wallets are scored.

   Price: 0.05 USDC
   Status: 200
   #1 primm  skill 88 (Sharp)  edge 13 pts
   #2 Kch-Temp  skill 76 (Sharp)  edge 6 pts
   …
   Paid. Transaction: 0x31a8…9169

   That's a real payment: search the transaction on basescan.org to see it. Now swap the URL for any other endpoint below. If something goes wrong, see Troubleshooting.

Endpoints

All endpoints are GET, return JSON shaped as { data, cached }, and live under https://www.x402pulse.dev.

market accepts a full polymarket.com link, a market slug, or a condition ID. If a link covers an event with several markets, you get a free 400 with choices[] to pick from.

Response fields

What every number means, so your agent can explain its answers.

In your own app

The same pattern in TypeScript. One wrapped fetch handles the whole exchange, and a spending cap means your agent can never overpay.

npm install @x402/fetch @x402/evm viem

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

const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.AGENT_KEY as `0x${string}`),
});

// Spending guardrail: refuse any single payment above $0.50.
client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
  if (Number(selectedRequirements.amount) / 1e6 > 0.5) {
    return { abort: true, reason: "Over my per-call limit" };
  }
});

const pay = wrapFetchWithPayment(fetch, client);

// Which way does skilled money lean on this market?
const market = "https://polymarket.com/event/…";
const res = await pay(
  "https://www.x402pulse.dev/v1/smart-money?market=" + encodeURIComponent(market),
);
const { data } = await res.json();
console.log(data.summary);
// e.g. "Skilled holders lean Yes (72% of skill-weighted money, from 4 skilled
//       holders), more confident than the market's 41%."

Errors and limits

Every error is free: payment only settles when the response succeeds.

How fresh is the data?

• Whales: refreshed every minute.
• Smart money: every 5 minutes.
• Wallet: every 10 minutes. A wallet's skill score: every 30 minutes.
• Top traders: every 15 minutes. Disagreements: rescanned in the background every 15 minutes. Skilled whales: every 3 minutes.
• Every response has cached: true or false, so you can tell whether it was just computed.

Troubleshooting

The problems people actually run into, and the fix for each.

What to build

A few ideas for products and agents on top of x402Pulse.