Guide · Permanent integration

Authorize permanent pay-per-call scoring

Most teams try EqBuilder as a one-off test. The real value is leaving it wired in: a standing tool inside your agent that scores (and fixes) every reply before it ships. After three free evaluations, an explicitly configured burner wallet lets the SDK sign each requested paid call — installation alone never charges. Here is the complete always-on setup, start to finish.

1. Fund a wallet once (gasless — signing only)

Create a fresh burner wallet and fund it with USDC on Base. That's the whole treasury step:

• Zero ETH needed. Payments are signed EIP-3009 transfer authorizations sent in an HTTP header; the platform's facilitator submits them on-chain and pays the gas.
• $5 covers roughly 100 basic scores at the list price (live numbers at /api/pricing).
• Use a dedicated burner — never a wallet holding funds you can't afford to lose. The key lives only in your agent's config.

2. Register the tool permanently

MCP — one block in any MCP client config. The MCP tools are the free tier (trial scoring, profiles, pricing, fee preview); paid settlement continues on the SDK/REST x402 flow below:

{
  "mcpServers": {
    "eqbuilder": {
      "type": "streamable-http",
      "url": "https://eqbuilder.dev/api/mcp"
    }
  }
}

Python — use eq.free_score(...) for your trial scores; wire eq.score(...) as the standing call. It quotes, signs, and settles the x402 payment automatically on every call:

> pip install "eqbuilder[payments]"

from eqbuilder import EqBuilder

eq = EqBuilder(wallet_key="0x<burner private key>")
result = eq.score(
    "Sounds good — I'll double-check the invoice and get back to you.",
    delay_seconds=4.2,
    profile="support_customer",
)

Node:

> npm install eqbuilder viem

import { EqBuilder } from "eqbuilder";

const eq = new EqBuilder({ walletKey: "0x<burner private key>" });
const result = await eq.score("...", {
  delaySeconds: 4.2,
  profile: "support_customer",
});

LangChain, CrewAI, and LangChain.js tool wrappers ship in both SDKs — pass the wallet key once at construction and the tool stays paid-up for the life of the agent.

3. The free → paid transition is seamless

Your first 3 scores are free with data_consent: true; wishlist feedback is optional and never interrupts them. Use the SDK auto_score/autoScore method with an authorized Base USDC wallet. When the trial ends, it reads the authoritative HTTP 402 quote, signs it, retries once, and returns the paid score. Without wallet authority, the HTTP 429 response carries one machine-readable developer handoff for the operator who controls funding.

4. Error handling — the whole contract

• HTTP 402: select the Base USDC requirement, sign its EIP-3009 authorization, and retry the same request once with PAYMENT-SIGNATURE. The SDKs do this for you; legacy X-PAYMENT clients remain compatible.
• 429 free_trial_exhausted: switch to the paid call (the response body tells you exactly how).
• Failed validations remain available: paid scoring stays fixed-price and repeatable, so a bot can improve and try again without suspension.
• 400 data_consent_required: free scoring needs explicit retention consent; the rejection never consumes a round.

A malformed payment is rejected before any money moves, and an unused signed authorization expires harmlessly. One caution: if a paid call times out after you sent a payment, don't blindly re-sign — the original may have settled. Check your wallet statement (below) and reconcile before paying again.

5. Top-up and audit

Watch the burner's USDC balance on-chain and refill when low (~$5 per 100 basic scores). Audit every charge free, any time: GET /api/wallet/{wallet_address}/statement?auth_tx_hash=TX, where the auth is any settled transaction hash your wallet has paid with (only the keyholder has one — foreign hashes get 403). It returns your full settled history grouped by product, reconciling exactly with the ledger. Fleets: prepaid bundles (POST /api/bundle) cut the per-score price at published discounts.