Getting started5 steps

Quickstart

Get from zero to a working x402 agent call in about five minutes. By the end you will have a funded agent wallet, an enabled service, and a verified paid API response.

1
Register

Create a Gordon account and buyer profile.

2
Create an agent

Add an agent — Gordon provisions its wallet and shows the scoped key once.

3
Fund your wallet

Deposit USDC on Base to the agent's wallet.

4
Review services

Curated services are pre-enabled — set spend caps or disable any you don't want.

5
Make a call

Use the MCP tool or SDK to make your first paid request.

Step 1

Register

Go to withgordon.ai and create an account. After email verification, Gordon creates your buyer profile. Wallets in Gordon are per agent — you provision and fund a wallet for each agent you create (next step), not at the account level.

No credit card is required at signup. Each agent gets a CDP-managed custody wallet on Base (Coinbase Developer Platform); you fund it with USDC through Coinbase Onramp in the dashboard or by sending USDC directly from any Base-compatible wallet or exchange. Gordon signs x402 authorizations on the agent's behalf but never holds your private keys.

Testnet mode
Gordon supports Base Sepolia for testing. When an agent's wallet is on a testnet, the agent's Fund modal recognizes it and links the matching USDC faucet (e.g. faucet.circle.com), and those calls do not move real funds.
Step 2

Create an agent

Go to Account → Agents → New agent. Give it a name (e.g. "research-bot") and click Create. Gordon provisions a CDP custody wallet on Base for the agent and auto-enrolls it into the curated service catalog at permissive defaults — so the agent is ready to call services as soon as its wallet is funded.

Gordon generates a key pair for the agent. Copy both halves — the secret is shown only once:

# Public key (safe to log)
gak_pub_abc123...

# Secret key (treat like a password — never log or commit)
gak_sec_xyz789...

# Combined — pass this as GORDON_AGENT_KEY
gak_pub_abc123...:gak_sec_xyz789...

The agent key is scoped to a single agent. If you compromise a key, rotate it in the dashboard — existing calls in flight will fail within 60 seconds as the cache expires.

Key security
Store the secret in an environment variable or secret manager. Never hardcode it in source code, commit it to git, or expose it in client-side JavaScript.
Step 3

Fund your wallet

Open your agent (Account → Agents → [your agent]) and click Fund. Gordon shows the agent's Base wallet address (and a Buy-with-Coinbase option); send USDC from any Base-compatible wallet or exchange.

Gordon uses micro-units internally: 1,000,000 units = $1.00 USD. For most catalog services, individual calls cost between 100 and 5,000 units ($0.0001 – $0.005). A $5 deposit provides thousands of API calls.

Fund with USDC only
You do not need ETH. Gordon signs native USDC EIP-3009 authorizations and the provider facilitator sponsors settlement gas on Base.
USDUnitsApprox. calls @ 1,000 units/call
$1.001,000,0001,000
$5.005,000,0005,000
$10.0010,000,00010,000
$50.0050,000,00050,000

Deposits confirm on Base in about 2 seconds. The balance is available immediately after on-chain confirmation.

Step 4

Review & limit services

New agents are auto-enrolled into the curated catalog at permissive limits, so your agent can call those services as soon as its wallet is funded — no manual enabling required to get started.

Go to Account → Agents → [your agent] → Services to tighten this. Set a per-call cap, restrict operations, or disable any service you don't want the agent to reach. Enforcement is fail-closed: a service that isn't in the agent's enabled set is blocked (service_not_enabled), so a compromised key can't spend on services you've disabled.

When a service is enabled, all its operations are allowed by default (enabled_operations: null). Restrict to specific operations from the service settings panel.

ServiceSlugTypical priceWhat it does
Exaexa~1,000 units/callAI-powered web search
Zlurpzlurp5,000 units/scrapeURL scraping to clean markdown
CoinGeckocoingeckoVaries by operationCrypto market and token data
Step 5

Your first paid call

With an agent key and a funded wallet, you can make your first call two ways: via the MCP server in your IDE, or via the TypeScript SDK directly.

Option A: Platform API (curl)

# 1. List catalog services (public — no auth required)
curl https://api.withgordon.ai/services

# 2. Authorize a payment for an Exa search (agent key required)
curl -X POST https://api.withgordon.ai/x402/authorize \
  -H "Authorization: Bearer gak_pub_...:gak_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "req_001",
    "service_id": "exa",
    "operation_id": "search.web",
    "payment_requirement": { ... },
    "max_payment_units": 50000
  }'

Option B: TypeScript SDK

npm install @withgordon/core
import { Gordon } from "@withgordon/core";

const gordon = new Gordon({
  platformUrl: "https://api.withgordon.ai",
  agentApiKey: process.env.GORDON_AGENT_API_KEY!,
  agentApiSecret: process.env.GORDON_AGENT_API_SECRET!,
});

// Drop-in replacement for fetch — handles the 402 → authorize → retry → confirm
// cycle. Pass serviceId + operationId so Gordon enforces the agent's service policy.
const { response, receipt } = await gordon.fetch("https://api.exa.ai/search", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "x402 protocol agentic payments", numResults: 5 }),
  serviceId: "exa",
  operationId: "search.web",
  maxPaymentUnits: 5000, // $0.005 cap; 1,000,000 units = $1.00
});

const data = await response.json();
console.log(data);
if (receipt?.confirmed) {
  console.log("Paid", receipt.amount_units, "units · settlement", receipt.settlement_id);
}

Receipt shape

{
  "settlement_id": "stl_abc123",
  "transaction_id": "txn_xyz789",
  "amount_units": 1000,
  "network": "base",
  "pay_to": "0x6d6E695b09861467c7d462f5AAF31cF3540B9192",
  "confirmed": true
}
receipt.confirmed
For non-402 responses receipt is null and the original Response is returned unchanged. receipt.confirmed === truemeans the provider returned payment proof and Gordon accepted the settlement. If a provider returns 2xx but settlement can't be confirmed, gordon.fetch() throws GordonPaymentError (unless you set allowUnconfirmed) — you won't silently receive data without knowing payment status.
MCP

MCP quickstart

If you prefer to work through your IDE rather than code, configure the Gordon MCP server in your client and ask it to call a service:

// .cursor/mcp.json or claude_desktop_config.json
{
  "mcpServers": {
    "gordon": {
      "url": "https://api.withgordon.ai/mcp",
      "headers": {
        "Authorization": "Bearer gak_pub_...:gak_sec_..."
      }
    }
  }
}

Then type a prompt in your IDE:

Search the web for recent papers about agentic payments using Exa and summarize the top 3.

The model will automatically call gordon_call_service with service_id: "exa". Gordon handles authorization, payment, and receipt — the model just gets the search results back.

See the MCP install page for client-specific setup instructions (Cursor, Claude Desktop, VS Code, Codex, Windsurf).

SDK

SDK quickstart

Install the Gordon TypeScript SDK:

npm install @withgordon/core
# or
yarn add @withgordon/core

Catalog services vs arbitrary x402 endpoints

import { Gordon } from "@withgordon/core";

const gordon = new Gordon({
  platformUrl: "https://api.withgordon.ai",
  agentApiKey: process.env.GORDON_AGENT_API_KEY!,
  agentApiSecret: process.env.GORDON_AGENT_API_SECRET!,
});

// Catalog service — pass serviceId + operationId so Gordon enforces
// the agent's service enablement + spend policy:
const { response } = await gordon.fetch("https://api.exa.ai/search", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "agentic web search", numResults: 3 }),
  serviceId: "exa",
  operationId: "search.web",
  maxPaymentUnits: 5000,
});

// Arbitrary x402 endpoint — omit serviceId/operationId. The call is still
// authorized + signed and capped by maxPaymentUnits, but there's no
// per-service policy to enforce:
const { response: raw } = await gordon.fetch("https://api.example.com/data", {
  method: "GET",
  maxPaymentUnits: 10_000,
});
Pass serviceId + operationId for catalog services
With serviceId and operationId, Gordon enforces the agent's per-service enablement and spend policy. Omit them only for unlisted x402 endpoints that aren't in the catalog — those calls are still authorized and capped by maxPaymentUnits, but there's no per-service policy to apply.
Next steps

What's next

MCP install guide →

Client-specific setup for Cursor, Claude Desktop, VS Code, Codex, and Windsurf.

API reference →

Full endpoint docs with request/response schemas and authentication details.

Error codes →

Complete error code table with resolution steps for every Gordon error.

Browse services →

Explore all available catalog services and their operations and pricing.