Developers · Agent API · Pay Harpd

Pay Harpd in ten lines

This is the shortest correct way for an autonomous agent to buy Harpd data. No signup, no API key, no human checkout — just a wallet with USDC and one HTTP request. The library does the 402 → sign → retry → settle dance for you.

0.Discover first (optional, free)

See the tools and their live prices before you code. No credential required.

curl -s https://api.harpd.com/mcp | jq '.tools[] | {name, pricing_mode, price_usd}'
# free: search_products, get_rank
# paid: harpd_compare ($0.01), harpd_research ($0.05),
#       harpd_optimize ($0.01), get_historical_data ($0.05)

1.The minimal paid call

Install @x402/fetch, @x402/core, @x402/evm, viem. One call, one payment.

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

// A wallet holding USDC on Base. The key stays in your runtime, never sent to Harpd.
const client = new x402Client()
client.register('eip155:*', new ExactEvmScheme(privateKeyToAccount(process.env.AGENT_WALLET_KEY)))
const paidFetch = wrapFetchWithPayment(fetch, client)

// The library reads the 402, signs the exact USDC amount (gas paid by the
// facilitator), retries with the signature, and returns 200 with the data.
const res = await paidFetch('https://api.harpd.com/api/agent/v1/compare', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ products: ['claude', 'gemini', 'gpt'] }),
})

const { data, meta } = await res.json()
// data        → head-to-head comparison
// meta.payment → the settled receipt (network, amount, tx hash)
// meta.citation → a ready-to-quote attribution line (CC BY 4.0)

2.No SDK? The raw handshake

If you cannot use the npm client, the whole protocol is HTTP + one EIP-712 signature. Any EVM library can produce it.

POST /api/agent/v1/compare  (no payment header)   →  HTTP 402
  PAYMENT-REQUIRED: 

# Decode the challenge to learn the exact amount, recipient and asset:
amount  = challenge.accepts[0].amount        # e.g. "10000" atomic USDC = $0.01
payTo  = challenge.accepts[0].payTo          # Harpd's treasury on Base
asset  = challenge.accepts[0].asset          # USDC contract

# Sign an EIP-3009 TransferWithAuthorization (from=you, to=payTo, value=amount),
# base64 the {x402Version, scheme, network, payload:{signature, authorization}} object,
# then retry the SAME request with that base64 as the PAYMENT-SIGNATURE header → 200.

# A settled payment is single-use: replaying it returns HTTP 409. Issue a new
# signature, never resend the old one.

3.Same wallet, MCP transport

Harpd is also an MCP server. Apply the same wrapper to the MCP transport and paid tools are signed transparently — no MCP-specific payment code.

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(
  new URL('https://api.harpd.com/mcp'),
  { fetch: wrapFetchWithPayment(fetch, client) },  // the same client from step 1
)
const mcp = new Client({ name: 'harpd-buyer', version: '1.0.0' }, { capabilities: {} })
await mcp.connect(transport)
const r = await mcp.callTool({ name: 'harpd_compare', arguments: { products: ['claude','gemini'] } })
// r.structuredContent.data  → comparison
// r._meta['harpd/payment']  → settled receipt

Prove it free
On mainnet, verify_agent_payment costs $0.01. On Base Sepolia the whole handshake runs for testnet USDC so you can confirm your signing path before spending real funds.