FOR AI AGENTS

SIGN UP ONCE, PAY FOR YOURSELF

A person signs up once and approves access. After that, an agent with a Base USDC wallet can check its balance, add credits, and keep working without waiting for anyone.

GET ACCESS

Run Connect without a key in an interactive terminal. It prints an approval URL and an 8-character code. A human opens the URL, signs up or logs in, optionally adds funds, and clicks Approve. Connect receives the API key once, then prints the team ID, balance, and the x402 top-up pointer when x402 is enabled.

--login forces device login. --no-login restores the API-key paste prompt. For CI and other non-interactive environments, set HAIMAKER_API_KEY.

npx -y @haimaker/connect

CHECK YOUR BALANCE

Call the team endpoint with the API key as a bearer token. The response includes max_budget, the credits paid in, and spend. Your available balance is max_budget - spend.

Use the team_id returned by device login or included in an HTTP 402 response.

curl "https://api.haimaker.ai/team/info?team_id=<team_id>" \
  -H "Authorization: Bearer $HAIMAKER_API_KEY"

WHEN YOU RUN OUT

Out of credits is HTTP 402. The body keeps the OpenAI error shape and adds payment details under provider_specific_fields. The topup object is present only when x402 top-ups are enabled.

Do not retry the model request while the balance is empty. Pay first, then retry it.

{
  "error": {
    "message": "<message>",
    "type": "budget_exceeded",
    "code": "402",
    "provider_specific_fields": {
      "billing_url": "<billing_url>",
      "team_id": "<team_id>",
      "balance_usd": 0,
      "topup": {
        "x402_url": "https://api.haimaker.ai/payments/x402/topup",
        "min_usd": 5,
        "network": "eip155:8453",
        "asset": "USDC"
      }
    }
  }
}

TOP UP WITH USDC

Post the amount in cents and the team ID. The minimum is 500 cents. The first request returns HTTP 402, with x402 v2 requirements in both the response body and the base64 PAYMENT-REQUIRED header.

1. REQUEST PAYMENT TERMS

curl -i -X POST https://api.haimaker.ai/payments/x402/topup \
  -H "Authorization: Bearer $HAIMAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":500,"teamId":"<team_id>"}'

The requirement uses scheme exact, Base mainnet eip155:8453, and USDC. The atomic amount is cents × 10^4, so 500 cents becomes 5,000,000. Send the payment to payTo in accepts[0].

HTTP/2 402
PAYMENT-REQUIRED: <base64-encoded x402 v2 requirements>

{
  "x402Version": 2,
  "error": "<error>",
  "resource": { "url": "https://api.haimaker.ai/payments/x402/topup", ... },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000000",
    "asset": "<USDC contract address>",
    "payTo": "<payTo>",
    "maxTimeoutSeconds": 600
  }]
}

2. SIGN ONCE, THEN RETRY

Sign an EIP-3009 authorization with an x402 client, such as Coinbase's x402 packages. Retry the same request with the base64 signature in PAYMENT-SIGNATURE.

curl -i -X POST https://api.haimaker.ai/payments/x402/topup \
  -H "Authorization: Bearer $HAIMAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <same_base64_signature>" \
  -d '{"amount":500,"teamId":"<team_id>"}'

200: CREDIT APPLIED

The response includes PAYMENT-RESPONSE with the transaction hash. The credit is now available.

202: SETTLEMENT PENDING

{"status":"settlement_pending"} means the transfer was broadcast but is not confirmed. Retry the same request with the same PAYMENT-SIGNATURE. Never sign a new payment because the nonce may already be consumed.

409: SIGNATURE CONFLICT

The signature was already credited to a different team or amount. Do not reuse it.

x402 payments are irreversible and count as real payments, so they lift the free-tier limits.

A HUMAN PAYS BY CARD

A human can add a card and turn on auto-recharge from the billing page or the device-approval screen. Agents do not manage card payments.

CONTRACT

Item	Value	Use
Signup	`https://app.haimaker.ai/sign-up`	One-time human signup
Connect	`npx -y @haimaker/connect`	Device login when no key is set
API key	`HAIMAKER_API_KEY`	Bearer credential for CI and API calls
Team ID	`team_id` / `teamId`	Read from login or 402; send as `teamId` for top-ups
Balance	`GET https://api.haimaker.ai/team/info?team_id=<team_id>`	`max_budget - spend`
Out of credits	`HTTP 402`, `type: budget_exceeded`, `code: "402"`	Pay before retrying the model request
Payment details	`provider_specific_fields`	`billing_url`, `team_id`, `balance_usd`, optional `topup`
x402 pointer	`topup.x402_url`, `min_usd`, `network`, `asset`	Discover the autonomous payment terms
Top-up	`POST https://api.haimaker.ai/payments/x402/topup`	JSON fields: `amount` in cents and `teamId`
Payment terms	`PAYMENT-REQUIRED`	Base64 x402 v2 requirements: `exact`, `eip155:8453`, USDC, atomic `amount`, `payTo`
Signed payment	`PAYMENT-SIGNATURE`	Base64 EIP-3009 authorization; reuse it after 202
Settlement	`PAYMENT-RESPONSE`	Transaction hash returned after a successful top-up