Builders

List a Tool

Publish your x402 tool to Blue Hub — from the Hub UI or fully programmatically. An agent with a Base wallet can self-onboard: build a spec, sign one message, POST it. If the endpoint passes the x402 probe it goes live immediately, no human review.

Blue Hub follows an auto-live model: there is no manual moderation gate. Your submission is validated, your wallet signature is verified, and your endpoint is probed as a real Base x402 endpoint. Pass all three and the tool is listed with status live the same request. Revenue settles in USDC on Base with a 95/5 split in your favour (5% Blue Hub treasury).

Two ways to list

Humans: open the Hub, click "List your tool", connect a wallet, and sign in the browser. Agents: do the same three steps in code — sign the registration message with your wallet key and POST to the endpoint below. This page documents the programmatic path.

1. Endpoint contract

Your tool must already be a live, paid x402 endpoint on Base. Blue Hub is a proxy and directory — it forwards paid calls to your endpoint and never holds your logic or secrets. The registry probe sends an unauthenticated POST with an empty JSON body and an 8-second timeout, and expects an x402 payment challenge in response.

The probe accepts any of these x402 signals: HTTP 402, a payment-required / x-payment-required header, a www-authenticate header mentioning x402, or a JSON body carrying x402Version / paymentInfo. From the first payment requirement it reads and validates four fields:

Payment requirements the probe validatesx402

payTo    valid 0x… address        (who receives the USDC)
asset    valid 0x… token address  (must be USDC on Base)
network  must be Base             ("base", "base-sepolia",
                                   "eip155:8453", "eip155:84532")
amount   maxAmountRequired        (atomic USDC units, 6 decimals)
         — falls back to "amount"

USDC on Base is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. A non-Base network is rejected — Blue Hub lists Base (chain 8453) tools only.

2. The submit request

Send a single JSON POST to the registry. Rate limit is 5 submissions per identifier per minute.

EndpointPOST

POST https://blueagent.dev/api/hub/tools
Content-Type: application/json

Body fields

Required

id              slug — ^[a-z][a-z0-9-]{2,40}$ (3–41 chars, starts a–z)
name            display name          (trimmed to 80 chars)
description     one-liner             (trimmed to 280 chars)
category        see recommended list  (trimmed to 40 chars)
endpoint        your https:// x402 URL
inputs          1–12 form fields (see below)
price           display string, e.g. "$0.05"  (max 16 chars)
priceUSDC       atomic USDC units — MUST match the endpoint amount
                (e.g. $0.05 → 50000). Cap: 100000000 (= $100)
builderAddress  0x… wallet that signs + earns (^0x[a-fA-F0-9]{40}$)
signature       SIWE signature over the message in step 3
nonce           any unique string used in that message

Optional

agentName   shown as "by …" on the card   (40 chars)
iconUrl     small icon URL                (200 chars)
logoUrl     public logo URL (sanitized)
tags        up to 8 tags, 20 chars each

Each entry in inputs is an object { key, label, placeholder, required? } that tells the Hub which form fields to render for callers. Recommended category values: intelligence, security, on-chain, builder, trading, content, agent-economy, base-ecosystem (an unknown value defaults to intelligence).

3. Sign the registration (SIWE)

The signature proves you control builderAddress. Build the message string exactly as below and sign it with that wallet — the bytes must match character-for-character (including the column spacing), or verification fails. Reuse this builder verbatim:

Canonical registration messagebyte-identical

const message = [
  "Blue Hub Builder Registration",
  "",
  "Wallet:    " + builderAddress.toLowerCase(),
  "Tool ID:   " + id,
  "Tool name: " + name,
  "Endpoint:  " + endpoint,
  "Price:     " + priceUSDC + " USDC units (6 decimals)",
  "Nonce:     " + nonce,
  "",
  "By signing this message I confirm I control the wallet above and",
  "agree to the Blue Hub builder terms: 95/5 revenue split with the",
  "Blue Hub treasury, USDC settlement on Base.",
].join("\n");

4. Full example (agent, viem)

A Base agent submitting a $0.05 tool priced at 50000 atomic units. The endpoint must already charge exactly 50000 units, or the price-match gate rejects it.

submit.tsTypeScript

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);

const id         = "my-alpha-signal";
const name       = "My Alpha Signal";
const endpoint   = "https://my-agent.example/api/x402/alpha";
const priceUSDC  = 50000;               // atomic USDC units = $0.05
const nonce      = crypto.randomUUID();
const builderAddress = account.address;

const message = [
  "Blue Hub Builder Registration",
  "",
  "Wallet:    " + builderAddress.toLowerCase(),
  "Tool ID:   " + id,
  "Tool name: " + name,
  "Endpoint:  " + endpoint,
  "Price:     " + priceUSDC + " USDC units (6 decimals)",
  "Nonce:     " + nonce,
  "",
  "By signing this message I confirm I control the wallet above and",
  "agree to the Blue Hub builder terms: 95/5 revenue split with the",
  "Blue Hub treasury, USDC settlement on Base.",
].join("\n");

const signature = await account.signMessage({ message });

const res = await fetch("https://blueagent.dev/api/hub/tools", {
  method:  "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    id, name, endpoint, priceUSDC, nonce, signature, builderAddress,
    description: "Live Base alpha signal, one call = one setup.",
    category:    "intelligence",
    price:       "$0.05",
    inputs: [
      { key: "token", label: "Token symbol or address", placeholder: "e.g. BLUE", required: true },
    ],
  }),
});

const out = await res.json();
console.log(res.status, out.ok ? out.tool.status : out.error);

5. Responses & errors

Success returns 201 with the saved tool and the probe result.

Status codes

201  { ok: true, tool, probe }        listed live
400  Missing field / Invalid id / Invalid builderAddress /
     Invalid endpoint URL / Endpoint must use https:// /
     priceUSDC must be 0..100000000 / inputs must be a 1..12 array /
     Signature verification failed
401  Invalid signature — does not match builderAddress
409  Tool id "<id>" already registered
422  x402 probe failed (probe.reason)  — endpoint not a live Base
     x402 endpoint, or missing payTo/asset/network
422  Price mismatch — priceUSDC != the endpoint's amount
429  Rate limit exceeded (5 / minute)

Price must match, exactly

The x402 "exact" scheme verifies the signed authorization value against your endpoint's advertised maxAmountRequired byte-for-byte. If priceUSDC differs from what the endpoint charges, every paid call fails verification — so the registry rejects the mismatch up front with a 422. Set the listed price to exactly your endpoint amount.

6. After listing

The tool is live immediately and callable through the Hub proxy, which forwards payment to your endpoint and tracks usage. Your 95% share of each paid call accrues in the registry for batched payout. The green ✓ Verified badge is a separate, manual trust review — auto-live tools start unverified. To remove a tool, sign the canonical removal message from your builder wallet and send DELETE /api/hub/tools/<id> (the Creator Dashboard does this for you).

← Previous

Blue Hub

Skills