venice-x402
Skill2 starsChanged 5 months agoMITView on GitHub
Manage Venice x402 wallet credits. Covers POST /x402/top-up (payment discovery + signed USDC settlement), GET /x402/balance/{walletAddress}, GET /x402/transactions/{walletAddress}, USDC on Base (chain 8453), minimum $5 top-up, transaction types TOP_UP/CHARGE/REFUND, and the x402 v2 PAYMENT-REQUIRED response shape returned by all inference endpoints.
- Reads credentials
- Installs packages
- Sends data out
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- veniceai/skillsedited, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- veniceai/skills★ 17114% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository19 other files it gives its agents.
- cheaptokensSkill
- venice-api-keysSkill
- venice-api-overviewSkill
- venice-audio-musicSkill
- venice-audio-speechSkill
- venice-audio-transcriptionSkill
- venice-augmentSkill
- venice-authSkill
- venice-billingSkill
- venice-charactersSkill
- venice-chatSkill
- venice-crypto-rpcSkill
- venice-embeddingsSkill
- venice-errorsSkill
- venice-image-editSkill
- venice-image-generateSkill
- venice-modelsSkill
- venice-responsesSkill
- venice-videoSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 198
Use offset + limit and pagination.hasMore for paging.
- Very specific: line 221
Use the x402 SDK (npm install x402) for signing.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Venice x402 (wallet credits)
x402 is Venice's wallet-based payment flow. Pay per request with USDC on Base, no account required. Three admin endpoints plus the protocol-level 402 response returned by every inference endpoint.
| Endpoint | Auth | Purpose |
POST /x402/top-up | None (discovery) / X-402-Payment (settlement) | Discover payment requirements, then settle a signed USDC transfer. |
GET /x402/balance/{walletAddress} | SIWE (X-Sign-In-With-X) | Current USD balance for a wallet. |
GET /x402/transactions/{walletAddress} | SIWE | Paginated ledger: TOP_UP, CHARGE, REFUND. |
For the SIWE header format itself, see venice-auth.
Pay with a wallet: end-to-end
1. Call an inference endpoint with no balance → 402
Any inference endpoint (e.g. POST /chat/completions) returns a 402 with structured topUpInstructions and siwxChallenge when the wallet balance is too low. The PAYMENT-REQUIRED response header carries the x402 v2 paymentRequired object (base64-encoded JSON containing x402Version, error, resource, accepts[], and optional extensions) — it is not the same payload as the 402 body, which is a richer balance/top-up document.
{
"error": "Payment required",
"code": "PAYMENT_REQUIRED",
"message": "Insufficient x402 balance",
"suggestedTopUpUsd": 10,
"minimumTopUpUsd": 5,
"supportedTokens": ["USDC"],
"supportedChains": ["base"],
"topUpInstructions": {
"step1": "POST /api/v1/x402/top-up with no payment header to get payment requirements",
"step2": "Sign a USDC transfer authorization using the x402 SDK (createPaymentHeader)",
"step3": "POST /api/v1/x402/top-up with the signed X-402-Payment header",
"receiverWallet": "<RECEIVER_WALLET_ADDRESS>",
"tokenAddress": "<USDC_TOKEN_ADDRESS>",
"tokenDecimals": 6,
"network": "eip155:8453",
"minimumAmountUsd": 5
},
"siwxChallenge": {
"info": { "domain": "api.venice.ai", "statement": "Sign in to Venice AI", ... },
"supportedChains": ["eip155:8453"]
}
}2. Discover payment requirements — POST /x402/top-up (no header)
curl -X POST https://api.venice.ai/api/v1/x402/top-upResponse 402:
{
"x402Version": 2,
"accepts": [{
"protocol": "x402",
"version": 2,
"network": "eip155:8453",
"asset": "<USDC_TOKEN_ADDRESS>",
"amount": "5000000", // base units; USDC = 6 decimals → 5 USDC
"payTo": "<RECEIVER_WALLET_ADDRESS>"
}]
}3. Sign a USDC transfer → POST /x402/top-up with X-402-Payment
The x402 SDK does the EIP-712 USDC transferWithAuthorization signing for you:
npm install x402import { createPaymentHeader } from 'x402'
import { Wallet } from 'ethers'
const wallet = new Wallet(process.env.WALLET_KEY!)
// 1. Discover
const discover = await fetch(`${base}/x402/top-up`, { method: 'POST' })
const { accepts: [req] } = await discover.json()
// 2. Sign payment for $10 (write your own amount in base units)
const amount = '10000000' // $10
const header = await createPaymentHeader({ ...req, amount }, wallet)
// 3. Settle
const settle = await fetch(`${base}/x402/top-up`, {
method: 'POST',
headers: { 'X-402-Payment': header },
})
const { data } = await settle.json()
console.log(data.newBalance, data.amountCredited, data.paymentId)200 response:
{
"success": true,
"data": {
"walletAddress": "0x...",
"amountCredited": 10,
"newBalance": 22.5,
"paymentId": "payment_01HZ..."
}
}4. Call inference again — credits are now debited from the wallet
The venice-x402-client SDK wraps steps 1–4: it catches 402, auto-tops-up to a configured amount, and retries.
GET /x402/balance/{walletAddress}
curl "https://api.venice.ai/api/v1/x402/balance/0xYOUR_WALLET" \
-H "X-Sign-In-With-X: <base64 siwe>"{
"success": true,
"data": {
"walletAddress": "0x...",
"balanceUsd": 12.5,
"canConsume": true,
"minimumTopUpUsd": 5,
"suggestedTopUpUsd": 10,
"diemBalanceUsd": 5.25 // optional — present if the wallet is linked to a Venice account with DIEM
}
}The SIWE signer must match the path wallet — 403 otherwise.
GET /x402/transactions/{walletAddress}
curl "https://api.venice.ai/api/v1/x402/transactions/0xYOUR_WALLET?limit=50&offset=0" \
-H "X-Sign-In-With-X: <base64 siwe>"{
"success": true,
"data": {
"walletAddress": "0x...",
"currentBalance": 12.35,
"transactions": [
{
"id": "ledger_01H...",
"amount": -0.15,
"balanceAfter": 12.35,
"type": "CHARGE",
"createdAt": "2026-04-03T12:34:56.000Z",
"requestId": "chatcmpl-...",
"modelId": "zai-org-glm-5-1"
},
{
"id": "ledger_01H...",
"amount": 10,
"balanceAfter": 12.5,
"type": "TOP_UP",
"createdAt": "2026-04-03T12:00:00.000Z",
"requestId": null,
"modelId": null
}
],
"pagination": { "limit": 50, "offset": 0, "hasMore": false }
}
}Transaction types
type | Sign of amount | Meaning |
TOP_UP | positive | /x402/top-up settlement. |
CHARGE | negative | Inference debit. requestId / modelId link back to the call. |
REFUND | positive | Failed request refund or manual adjustment. |
Query parameters
/x402/transactions/{walletAddress}
| Param | Notes |
limit | 1–100. Default 50. |
offset | Number of entries to skip. Default 0. |
Use offset + limit and pagination.hasMore for paging.
Constants
- Chain — Base mainnet, chain ID
8453(eip155:8453). - Token — USDC (6 decimals). Native USDC on Base; not USDbC.
- Minimum top-up —
$5by default. A small number of allow-listed wallets (e.g. internal test wallets) may have a lower per-wallet override — always use theminimumTopUpUsdreturned intopUpInstructions//x402/balancerather than hardcoding5. - x402 SDK —
npm install x402for raw payment header signing, orvenice-x402-clientfor the managed Venice flow. - Receiver wallet + token contract are returned in
topUpInstructions; don't hardcode them.
Errors
| Code | Meaning |
400 | Below minimum top-up, invalid wallet format, or other validation. |
401 | X-Sign-In-With-X header is present but invalid (bad signature, expired, nonce reuse, unsupported chain) — returned as X402_SIGN_IN_* error codes. |
402 | Expected discovery response on /x402/top-up (no payment header), on /x402/balance and /x402/transactions when the SIWE header is absent, and on any inference endpoint when the wallet balance is insufficient. Settlement errors use INVALID_PAYMENT / INVALID_PAYMENT_FORMAT / INSUFFICIENT_FUNDS / EXPIRED_PAYMENT codes. |
403 | SIWE wallet ≠ path wallet. |
429 | Too many top-ups/balance checks. |
500 | Settlement failure; retry with a fresh nonce. |
Gotchas
- Use the x402 SDK (
npm install x402) for signing. Hand-rolling the EIP-712transferWithAuthorizationis risky — nonce reuse ⇒INVALID_PAYMENT. - The SIWE signer wallet must match the
walletAddresspath param onbalance/transactions. Separate wallets can't inspect each other. /x402/top-upis unauthenticated on the discovery call — auth is implicit via the signedX-402-Paymentheader on settlement.balanceUsdon/x402/balanceis the USDC credit balance only.diemBalanceUsd, when present, is a separate linked-account number — sum them yourself if you need a combined figure.PAYMENT-REQUIRED(uppercase, hyphens) is the header with base64-encoded x402paymentRequiredobject; don't confuse it with the body fieldcode: "PAYMENT_REQUIRED"(which only appears on insufficient-balance bodies, not on auth-style 402s).- On
/x402/balanceand/x402/transactions, missing the SIWE header returns402(not 401). Only a present-but-invalid header returns401with aX402_SIGN_IN_*code. - The x402 v2
accepts[].amountis in base units (e.g."5000000"= 5 USDC). Don't multiply by decimals again. DIEM,BUNDLED_CREDITS, and Bearer-accountUSDare independent from wallet credits. For account balance, usevenice-billing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

