CLI & MCP

@aispace.bot/x402 is an optional convenience layer: one package that runs as a CLI and an MCP server, and it carries the x402 payment step for you.

Protocol default remains stock HTTP with @x402/fetch + @x402/evm — see Quickstart. The gateway must work without this package.

The three routes, in order

Route	Setup	When to use it
1. Stock x402 — default	`@x402/fetch` + `@x402/evm` (or any stock buyer).	Stranger agents / protocol interop bar. See Quickstart.
2. CLI (`npx`) — convenience	One command; nothing to install. Set `AISPACE_X402_KEY` for paid calls.	Shell-out agents that prefer our wrapper.
3. MCP server — complementary	One-time `mcp.json` entry, then call tools.	Cursor, Claude Desktop, persistent hosts.

Origin: https://x402.aispace.bot · built in Venice · pay AiSpace in USDC on Base.

Machine discovery: /llms.txt · /.well-known/x402.json · /openapi.json.

CLI (npx)

# free discovery
npx @aispace.bot/x402 models --type text
npx @aispace.bot/x402 openapi
npx @aispace.bot/x402 quote --kind video --body '{"model":"wan-2-7-text-to-video","duration":"5s","aspect_ratio":"16:9","resolution":"720p"}'
# duration/aspect/resolution must be in that model's model_spec.constraints
 
# paid
export AISPACE_X402_KEY=0x<base-wallet-private-key-funded-with-usdc>
# Exact catalog ids only — resolve via GET /api/v1/models or /models/traits
npx @aispace.bot/x402 chat --model venice-uncensored-1-2 --message "hi" --max-tokens 256
npx @aispace.bot/x402 call --path api/v1/image/generate --body '{"model":"...","prompt":"..."}'

Add --json where supported for raw responses. Paid commands run the full 402 → sign → retry loop.

Programmatic API

import { call } from '@aispace.bot/x402'
import { generateAsync, waitForAsyncJob } from '@aispace.bot/x402/async'
import { writeFileSync } from 'node:fs'
 
// Binary responses (edit / speech / retrieve) → use result.buffer
const speech = await call({
  path: 'api/v1/audio/speech',
  body: { model: 'tts-kokoro', input: 'hello', voice: 'af_alloy' },
})
if (speech.buffer) writeFileSync('hello.mp3', speech.buffer)
 
const job = await generateAsync({
  kind: 'music',
  body: { model: 'ace-step-15', prompt: 'calm ambient loop', duration_seconds: '60' },
})
writeFileSync('track.mp3', job.buffer)

Concern	Guidance
Binary vs JSON	`image/generate` and `images/generations` are JSON. Edit/upscale/bg-remove, TTS, and async retrieve are binary (`result.buffer`)
Chat / thinking models	Empty `message.content` can still be success — also read `reasoning_content` / `reasoning_details`. Or send `venice_parameters.disable_thinking: true`. See Sync routes
Async complete	Best-effort after retrieve; gateway may return `{ alreadyCompleted: true }`
Multipart ASR/voices	Send `model` as a form field; pricing reads multipart text fields
Music quote vs queue	Quote uses pricing fields only (`model`, `duration_seconds`); queue also needs `prompt`

MCP server

{
  "mcpServers": {
    "aispace-x402": {
      "command": "npx",
      "args": ["-y", "@aispace.bot/x402", "mcp"],
      "env": { "AISPACE_X402_KEY": "0x<base-wallet-private-key>" }
    }
  }
}

Tool	Paid?	Purpose
`aispace_models`	free	list models
`aispace_openapi`	free	OpenAPI + `info.x-pricing`
`aispace_quote`	free	audio/video `{ quote }`
`aispace_chat`	paid	chat completions (402 loop)
`aispace_call`	varies	generic `/api/v1/*` call with 402 when needed

Environment

Variable	Required for	Description
`AISPACE_X402_KEY`	paid CLI / MCP tools	Base wallet private key with USDC. Env only — never a CLI flag. Key stays local.
`AISPACE_X402_BASE`	optional	Override origin (default `https://x402.aispace.bot`).

When to use what

CLI — default. Scripts, cron, agent frameworks that shell out.
MCP — complementary. Hosted agents with tool calling.
Stock x402 — protocol default. Quickstart · Auth and payment.

All three hit the same origin and the same Venice-equivalent × margin pricing. Live 402 amounts are authoritative; see Pricing.

Quickstart Auth and payment