Pay an API call with 1 USDC.
17 production x402 endpoints on Base mainnet. EIP-3009 signed. ERC-8004 agent card. One HTTP round trip, no API keys — your wallet is the auth.
- Endpoints
- 17
- Chain
- Base · 8453
- Settlement
- USDC
- Auth
- Wallet signature
01 · Quickstart
Trigger a 402 in 30 seconds.
One curl produces an x402 challenge. Sign with EIP-3009, retry with the X-Payment header, the asset is delivered. No keys to provision, no portal to register on.
curl -i -X POST https://app.suedeai.ai/create-music \
-H "Content-Type: application/json" \
-d '{"prompt":"lofi beat","durationSeconds":120}'HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: <base64-encoded x402 challenge>
{
"x402Version": 2,
"accepts": [{
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"amount": "200000",
"payTo": "0xb5a05466712fd5bcdf2883f43cC6B1799428032d",
"maxTimeoutSeconds": 300,
"extra": { "name": "USD Coin", "version": "2" }
}]
}- amount
- 200000 atomic USDC = $0.20 — settles on Base mainnet via the x402 facilitator.
- asset
- USDC on Base (0x833589…2913). Mainnet only; Sepolia available on request.
- payTo
- Suede payout wallet. Receives the EIP-3009-authorized transfer.
The challenge is also returned in the PAYMENT-REQUIRED header as a base64-encoded JSON payload, so SDKs can read it without parsing the body. The facilitator at x402.org/facilitator verifies and settles the signed authorization before the asset is generated — one HTTP round trip end-to-end.
02 · Python SDK
pip install suede-ai
The official Python SDK wraps the entire 402-challenge / EIP-3009 sign / retry loop. Seventeen pay-per-call endpoints, settled in USDC on Base — no API keys, no subscriptions. Your agent code writes prompts, not typed-data signatures.
pip install suede-aiRequires Python 3.10+. Pulls in httpx, eth-account, and pydantic. The first call returns 402; the SDK signs an EIP-3009 transferWithAuthorization for USDC on Base, replays with X-PAYMENT, and hands you the JSON — you never touch the typed data.
from suede_ai import SuedeClient
# Funded EOA on Base with USDC. Treat this like any secret.
PRIVATE_KEY = "0x..."
with SuedeClient(wallet_private_key=PRIVATE_KEY) as suede:
track = suede.create_music(
prompt="lo-fi rainy afternoon, vinyl crackle, soft piano",
duration_seconds=30,
)
print(track["assetUrl"]) # https://cdn.suedeai.xyz/audio/trk_...mp3
print(track["provenance"]) # {"fingerprint": "0x..."} on-chain attestationEndpoint signatures track the live manifest at /.well-known/x402.json. Prefer the raw HTTP handshake or another language? The next section has TypeScript, Python, and Go samples that run the same flow by hand.
03 · Integrate
Three steps. Three languages.
Discover endpoints, sign payment, call the route. Each sample handles the full 402-then-retry handshake against the live Suede x402 facilitator.
import { createWalletClient, http, parseSignature } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });
// 1. Discover live endpoints
const discovery = await fetch("https://app.suedeai.ai/.well-known/x402.json")
.then((r) => r.json());
// 2. First call returns 402 with payment requirements
const unpaid = await fetch("https://app.suedeai.ai/create-music", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ prompt: "lofi beat", durationSeconds: 120 }),
});
const challenge = await unpaid.json();
const req = challenge.accepts[0];
// 3. Sign EIP-3009 TransferWithAuthorization
const now = Math.floor(Date.now() / 1000);
const authorization = {
from: account.address,
to: req.payTo,
value: BigInt(req.amount),
validAfter: BigInt(Math.max(0, now - 600)),
validBefore: BigInt(now + (req.maxTimeoutSeconds ?? 300)),
nonce: `0x${crypto.randomUUID().replace(/-/g, "")}${"00".repeat(8)}` as `0x${string}`,
};
const signature = await wallet.signTypedData({
account,
domain: { name: "USD Coin", version: "2", chainId: 8453, verifyingContract: USDC_BASE },
types: { TransferWithAuthorization: [
{ name: "from", type: "address" }, { name: "to", type: "address" },
{ name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" },
{ name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" },
]},
primaryType: "TransferWithAuthorization",
message: authorization,
});
const xPayment = Buffer.from(JSON.stringify({
x402Version: 2, scheme: req.scheme, network: req.network,
payload: { authorization, signature },
})).toString("base64");
// 4. Retry with X-Payment header, asset is delivered
const paid = await fetch("https://app.suedeai.ai/create-music", {
method: "POST",
headers: { "Content-Type": "application/json", "X-PAYMENT": xPayment },
body: JSON.stringify({ prompt: "lofi beat", durationSeconds: 120 }),
});
const asset = await paid.json();
console.log(asset.url);The TypeScript sample mirrors @/lib/x402-client.ts from the Suede app itself. Production wallets should add idempotency keys (X-Idempotency-Key), nonce reuse protection, and exponential backoff on facilitator timeouts.
04 · Well-known
Discovery endpoints.
Every route is enumerable from a small set of well-known JSON manifests. Point an agent runtime at any of these and it can self-serve.
| Manifest | Purpose | Live |
|---|---|---|
| /.well-known/x402.json | Live x402 discovery manifest — all 17 paid endpoints with prices, networks, and asset addresses. | Open ↗ |
| /.well-known/agent-card.json | ERC-8004 agent card. Identity, capabilities, payment surface, and registry pointers. | Open ↗ |
| /.well-known/agentic-commerce.json | Agentic Commerce manifest — offerings, contact, and intent endpoints for buyer agents. | Open ↗ |
| /.well-known/virtuals-acp.json | Virtuals ACP manifest. Pointer to the Producer by Suede Labs execution agent. | Open ↗ |
| /.well-known/ai-plugin.json | OpenAI-compatible plugin manifest. Lets ChatGPT-style runtimes discover the OpenAPI schema. | Open ↗ |
| /llms.txt | Plain-text crawl summary for LLM indexers. Endpoints, pricing, and protocol surface in one file. | Open ↗ |
05 · Catalog
17 live endpoints.
All paid in USDC on Base mainnet. Prices range from $0.02 (style coach) to $1.50 (short video). Grouped by tier; click a row to inspect the live x402 challenge.
●Music·2 endpoints
- POST/agent/generate
Generate an original Suede media asset through the programmable IP stack, using music creation as the output function.
$0.20USDC402 ↗ - POST/create-music
Create a rights-aware media asset with Suede AI, using music generation inside Suede's programmable IP and licensing workflow.
$0.20USDC402 ↗
●Video·1 endpoint
- POST/agent/video
Generate a short Suede media clip for creator IP, product, and music workflows.
$1.50USDC402 ↗
●Musician Tools·12 endpoints
- POST/v1/extend
Extend an existing Suede-registered track by appending a natural continuation in the same style. Suede Extend.
$0.40USDC402 ↗ - POST/v1/cover
Generate a stylistic cover (re-imagining) of an existing Suede track. Suede Cover.
$0.40USDC402 ↗ - POST/v1/voice-cover
Replace the lead vocal of an uploaded track with a target Suede voice. Suede Voice Cover.
$0.40USDC402 ↗ - POST/v1/continue
Continue an uploaded audio file beyond its current length, preserving style and key. Suede Continue.
$0.40USDC402 ↗ - POST/v1/stems?mode=full
4-track stem separation: vocals, drums, bass, other. Suede Stems Pro.
$0.40USDC402 ↗ - POST/v1/stems?mode=basic
2-track stem separation: vocals + instrumental. Suede Stems.
$0.20USDC402 ↗ - POST/v1/vox
Isolate the vocal stem (acapella) from a source track. Suede Vox.
$0.20USDC402 ↗ - POST/v1/midi
Transcribe a source audio file into a MIDI file. Suede MIDI.
$0.10USDC402 ↗ - POST/v1/wav
Render a high-quality WAV master from a source track. Suede Master.
$0.10USDC402 ↗ - POST/v1/lyric-sync
Generate timestamped (synced) lyrics for a track. Suede Lyric Sync.
$0.10USDC402 ↗ - POST/v1/lyrics
Generate fresh song lyrics from a creative prompt. Suede Lyrics.
$0.04USDC402 ↗ - POST/v1/style-coach
Expand a short style-tag seed into a richer prompt-ready style brief. Suede Style Coach.
$0.02USDC402 ↗
●Rights·1 endpoint
- GET/v1/rights/{assetHash}
Resolve Suede Registry attestation for a content hash on Base — owner, IP account, token id, on-chain metadata, and explorer URL.
$0.005USDC402 ↗
●Analysis·1 endpoint
- POST/v1/analyze
Analyze an audio URL and return BPM, key, mode, energy, danceability, loudness, duration, and suggested genre.
$0.003USDC402 ↗
06 · Don't want to integrate?
Hire the agent.
Producer by Suede Labs is a Virtuals ACP agent that executes the same primitives on your behalf — paid by the deliverable, not by the API call.
Producer by Suede Labs
Producer is a live Virtuals ACP agent priced by deliverable. It wraps Suede’s programmable-IP stack — fingerprinting, registry attestation, and royalty routing — into seven consulting offerings agents can call. Pay once in $VIRTUAL, get a rights-aware asset back.
- $3
Agent Quick Score
1-page markdown scorecard grading any Virtuals/Bazaar agent on positioning, offering quality, pricing, and traction.
- $19
ACP Performance Audit
Deep audit of an ACP seller's offerings, pricing, SLAs, and jobs history. Per-offering grades plus a 30-day action plan.
- $39
ACP Offer Optimization
Rewrite a single ACP offering for Bazaar discoverability. Primary version, two A/B variants, keyword list, expected-lift call.
- $39
x402 Promotion Plan
14-day launch plan for an x402 endpoint or Bazaar listing. Day-by-day calendar, content pack, distribution targets, success metrics.
- $29
ACP Market Arbitrage Report
Arbitrage memo across 3-5 Bazaar categories. Under/over-priced listings flagged plus three named arbitrage plays.
- $15
ACP Buyer Growth List
20+ likely-buyer agents for a seller's offerings. Prospect table, top-5 sequencing, disqualifier list.
- $49
ACP Agent Setup
End-to-end setup playbook for launching a new ACP agent. Positioning, 4-6 offerings, infra checklist, day 1-7 plan.