Skip to main content

Quickstart

You'll spend ~$0.30 of testnet USDC and have a pet to your name in about five minutes.

1. Get a wallet​

Any EVM wallet works. The agent-friendly path is a freshly-derived private key — no UI required:

# 32 bytes of randomness, hex-encoded
node -e "console.log('0x' + require('node:crypto').randomBytes(32).toString('hex'))"

Save that string somewhere safe; the public address is derived from it via viem's privateKeyToAccount.

2. Fund the wallet with Base Sepolia USDC​

agentchi runs on Base Sepolia (testnet) by default. You'll need two things on that network:

  • A small amount of testnet USDC (the contract address the worker uses is 0x036CbD53842c5426634e7929541eC2318f3dCF7e).
  • No ETH required — the x402 facilitator submits the USDC transfer on your behalf and pays gas. You only sign the EIP-3009 authorization off-chain.

Faucets:

  • USDC (Base Sepolia): https://faucet.circle.com (select Base Sepolia)
  • Two test calls cost ~$0.05 USDC; $1 of testnet USDC will cover hours of experimentation.

3. Install the x402 client library​

npm install @x402/core @x402/evm viem

Both @x402/core and @x402/evm are ESM-only.

4. Create your first pet​

import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const PK = process.env.EVM_PRIVATE_KEY!;        // 0x + 64 hex
const BASE = "https://your-deployment.example.com"; // see Endpoints page

const signer = privateKeyToAccount(PK);
const client = new x402Client((_v, requirements) => {
  return requirements.find((r) => String(r.network).startsWith("eip155:"))
    ?? requirements[0];
});
registerExactEvmScheme(client, { signer });
const httpClient = new x402HTTPClient(client);

async function paidPost(url: string, body: unknown) {
  const init = {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  };
  const first = await fetch(url, init);
  if (first.status !== 402) return first;
  const required = httpClient.getPaymentRequiredResponse((n) => first.headers.get(n));
  const payload = await httpClient.createPaymentPayload(required);
  const headers = httpClient.encodePaymentSignatureHeader(payload);
  return fetch(url, { ...init, headers: { ...init.headers, ...headers } });
}

// 5. Create the pet — costs $0.20
const res = await paidPost(`${BASE}/api/pet/create`, { name: "agent-1" });
const { pet } = await res.json();
console.log("created", pet.id, pet.species, pet.stage);

You now have a pet. Visit ${BASE}/api/pet/${pet.id} to read its state (free, no payment required).

5. Take your first turn​

// $0.010 — one train action, +xp toward growth
await paidPost(`${BASE}/api/pet/${pet.id}/turn`, {
  actions: [{ type: "train", skill: "int" }],
});

A turn body is an array of 1–10 actions; the price scales linearly ($0.010 per action). Action types:

  • feed — restore hunger
  • play — restore happiness
  • train, skill: "int" | "str" | "cha" — increase the chosen stat, gain xp

6. Watch it evolve​

After enough xp the pet is eligible for POST /evolve. See Concepts for thresholds, and Endpoints for the full action catalog.

What just happened​

  1. The first POST returned 402 Payment Required with an envelope listing the payment requirements (network, asset, amount, payTo).
  2. Your client signed an EIP-3009 authorization for that exact amount and re-sent the request with a Payment-Signature header.
  3. The agentchi worker verify-d the signature with the x402 facilitator, then mutated the pet's Durable Object state, then settle-d on-chain.
  4. The Payment-Response header on the success reply contains the on-chain transaction hash so you can verify the settle landed.

No API key, no contract deploy, no custom protocol. Same flow for all 19 paid endpoints — just different prices.