Buy Harpd Rank Intelligence from your AI agent via x402

Harpd Rank is a transparent leaderboard where products compete for Overall, Monthly, and Weekly positions. The data is useful to more than humans: a competitor-monitoring agent, a VC research agent, or a “which product should I recommend” agent all benefit from knowing current Top-100 positions, daily movement, and Rank-Point provenance.

This post shows how to let your agent fetch that data programmatically — paying per request with x402, so there is no API key to apply for and no invoice to reconcile.

What your agent gets

Endpoint	Cost	Notes
GET /api/agent/v1/rankings	free	Top-100 listings for a scope/category
GET /api/agent/v1/products/{slug}	free	One product’s public profile
GET /api/agent/v1/premium/rank-intelligence	0.1 USDC (mainnet) / 0.001 USDC (testnet)	Full Rank Intelligence: positions, movement, history, category summaries, #100 threshold

Payment is settled on Base (mainnet eip155:8453, testnet eip155:84532) in USDC. Try the two free endpoints first; only rank-intelligence requires payment.

Discovery

Your agent does not need to hardcode anything. Harpd publishes a machine-readable index:

• https://api.harpd.com/.well-known/agent.json — single entry point (catalog, OpenAPI, endpoints, payment info)
• https://api.harpd.com/api/agent/v1/catalog — the full resource catalog
• https://api.harpd.com/openapi.json — OpenAPI 3.1 spec

Every 402 from the paid endpoint also carries an x402 Bazaar discovery extension describing the exact input/output schemas, so an x402-capable client can call it without prior documentation.

The flow

agent GET /premium/rank-intelligence
  → 402 Payment Required  (amount, USDC address, facilitator, Bazaar schema)
agent signs a USDC payment (holds its own key)
agent retries with the payment in a header
  → 200  Rank Intelligence JSON

No card rails. No checkout. The agent pays and receives in one round trip.

Quickstart (Node.js)

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

import { x402HTTPClient } from '@x402/fetch'
import { x402Client } from '@x402/core/client'
import { ExactEvmScheme } from '@x402/evm/exact/client'
import { privateKeyToAccount } from 'viem/accounts'

// Prod (Base mainnet) or the Base Sepolia test worker:
const baseUrl = process.env.AGENT_MARKET_URL ?? 'https://api.harpd.com'
const url = `${baseUrl}/api/agent/v1/premium/rank-intelligence?scope=weekly&category=all`

const account = privateKeyToAccount(process.env.TEST_AGENT_PRIVATE_KEY as `0x${string}`)
const client = new x402Client()
client.register('eip155:*', new ExactEvmScheme(account))
const http = new x402HTTPClient(client)

// 1) The unpaid call returns 402 with the challenge:
const challenge = await fetch(url)
console.log('challenge ->', challenge.status) // 402

// 2) Pay + retry in a single call; the client handles signing and settlement:
const res = await http.fetch(url)
if (!res.ok) throw new Error(`payment failed: ${res.status}`)
const intel = await res.json()
console.log('products returned ->', intel.products.length)
console.log('top movers ->', intel.products.slice(0, 3).map((p: any) => `${p.title} ${p.movement}`))

Environment

Variable	Value
TEST_AGENT_PRIVATE_KEY	A wallet your agent controls (signs payments)
AGENT_MARKET_URL	https://api.harpd.com (mainnet) or https://harpd-collector-testnet.2011yamaguchi.workers.dev (Base Sepolia)
ALLOW_MAINNET_PAYMENT	true only when calling mainnet (real USDC)

The full guarded version (with replay and status checks) lives in collector/scripts/agent-market-x402-e2e.mjs.

Getting test USDC

For the Base Sepolia test worker, fund a fresh wallet from a Base Sepolia USDC faucet and set AGENT_MARKET_URL to the testnet URL above. Each call costs 0.001 testnet USDC. No real money, full end-to-end flow.

Notes

• Machine payments are accounted separately from human Credits and Stripe — they never touch the same ledger.
• The paid response is deterministic and replay-safe: the same payment signature is rejected with 409 on retry, so agents can safely retry.
• Want the data shape before writing code? Hit /api/agent/v1/rankings (free) to see the listing structure, then pay only when you need movement history and the #100 threshold.

That’s the whole integration. Point your agent at the catalog, let it pay on 402, and it owns Rank Intelligence.