Agent API (x402)Quickstart

Quickstart

Stock x402 is the default agent path. Use @x402/fetch + @x402/evm. The CLI/MCP package is complementary convenience — the gateway must work without it.

RouteCommand / docs
1. Stock x402 (default)@x402/fetch + @x402/evm — below · x402 buyer quickstart
2. CLI (convenience)npx @aispace.bot/x402 … — CLI & MCP
3. MCP (convenience)npx -y @aispace.bot/x402 mcp — CLI & MCP

Requirements (paid): wallet with USDC on Base. Free catalogs need no wallet.

Base URL: https://x402.aispace.bot

Stock HTTP + @x402/fetch

1. GET /openapi.json                         → discover + x-pricing + x-guidance
2. GET /api/v1/models?type=text              → free catalog
3. POST /api/v1/chat/completions (no pay)    → 402 + Payment-Required
4. Retry with PAYMENT-SIGNATURE              → model response + PAYMENT-RESPONSE

Discover

curl -sS "https://x402.aispace.bot/openapi.json" | head
curl -sS "https://x402.aispace.bot/.well-known/x402.json"
curl -sS "https://x402.aispace.bot/llms.txt"

Free catalog

curl -sS "https://x402.aispace.bot/api/v1/models?type=text"
curl -sS -i \
  -H "Content-Type: application/json" \
  -d '{"model":"venice-uncensored-1-2","messages":[{"role":"user","content":"hi"}],"max_tokens":256}' \
  "https://x402.aispace.bot/api/v1/chat/completions"

Expect HTTP 402. Pay the live accepts[0].amount, then resend identically with PAYMENT-SIGNATURE (aliases: X-402-Payment / X-Payment). See Auth and payment.

Minimal Node buyer (stock packages only):

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch'
import { registerExactEvmScheme } from '@x402/evm'
import { privateKeyToAccount } from 'viem/accounts'
 
const account = privateKeyToAccount(process.env.PRIVATE_KEY)
const fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ register: registerExactEvmScheme, network: 'eip155:8453', signer: account }],
})
 
const res = await fetchWithPay('https://x402.aispace.bot/api/v1/chat/completions', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    model: 'venice-uncensored-1-2',
    messages: [{ role: 'user', content: 'hi' }],
    max_tokens: 64,
  }),
})
console.log(res.status, res.headers.get('PAYMENT-RESPONSE') ? 'settled' : 'no-receipt')
console.log(await res.json())

On 200, read choices[0].message.content and reasoning_content / reasoning_details. Thinking models can return empty content while filling those fields — that is still success. See Sync routes → Reasoning models.

CLI (complementary)

npx @aispace.bot/x402 models --type text
export AISPACE_X402_KEY=0x<key>
npx @aispace.bot/x402 chat --model venice-uncensored-1-2 --message "hi" --max-tokens 256

Accurate video price before paying:

npx @aispace.bot/x402 quote --kind video --body '{"model":"wan-2-7-text-to-video","duration":"5s","aspect_ratio":"16:9","resolution":"720p"}'

Testing without spending mainnet USDC

The production gateway settles real USDC on Base mainnet (eip155:8453) and does not currently accept testnet payments. To validate your buyer loop end-to-end without spending mainnet USDC:

  1. Exercise the 402 contract for free. Every paid route returns a real 402 + Payment-Required challenge when called unpaid — no wallet needed. Confirm your client parses accepts[0] (scheme exact, network eip155:8453, USDC asset, amount, payTo, maxTimeoutSeconds) and builds a PAYMENT-SIGNATURE from it. This covers discovery, challenge parsing, and request construction.
  2. Validate against the CDP facilitator on Base Sepolia in your own sandbox. Point a stock @x402/fetch + @x402/evm buyer at a test resource using network eip155:84532 (Base Sepolia) to confirm your signing and retry logic settle correctly through the same facilitator AiSpace uses — then flip to eip155:8453 for production. See the CDP seller docs.
  3. Probe a real price cheaply. The minimum charge is info.x-pricing.minChargeUsd (see the live OpenAPI). A minimal max_tokens chat call is the cheapest real settle if you want one mainnet receipt.

Next

OverviewCLI & MCP