Setting the file. One moment.
Subchapter 2.24
plugins/venice.mdMarkdown16 KBView on GitHub
[!IMPORTANT] Run Base MCP onboarding first (see
SKILL.md). Venice requests need either a Venice API key or a Base-wallet x402 flow; x402 sign-in and top-ups must be approved through Base MCP before paid calls.
Venice AI (opens in a new tab) is a privacy-focused, OpenAI-compatible AI API for chat, responses, image, audio, video, embeddings, and web/search tools. This plugin calls https://api.venice.ai/api/v1 over HTTP for inference and discovery, and uses Base MCP only for the wallet-authenticated x402 path: signing Sign-In-With-X messages with sign and, when available, making USDC top-ups on Base through Base MCP’s x402 payment tool. Normal API-key calls do not submit onchain transactions through Base MCP.
Venice supports two independent auth paths. Prefer the path the user has explicitly requested or already configured. The frontmatter uses siwe-jwt because the x402 wallet path is the Base-native flow: Base MCP signs the SIWE/SIWX message and, when needed, pays x402 top-ups. The Venice API-key path is a user-supplied bearer header that does not touch Base MCP; the single-value auth enum cannot fully express both models.
Use a Venice API key as a bearer token. This is account-scoped, tied to the user’s Venice account and DIEM balance, and overlaps with x402 on most paid inference endpoints:
{
"Authorization": "Bearer <VENICE_API_KEY>",
"Content-Type": "application/json"
}Do not ask the user to paste an API key into public chat if the harness has a secret/env-var mechanism. If the user must provide the key manually, they must paste the API key in its entirety, exactly as issued by Venice. Never truncate, abbreviate, infer, reconstruct, or partially paste a Venice API key; a partial key is invalid and can cause confusing auth failures. Never echo API keys back to the user.
x402 uses wallet identity plus prepaid USDC credits. This path is wallet-scoped and uniquely owns the wallet-credit endpoints: /x402/balance, /x402/transactions, and /x402/top-up. Venice accepts SIGN-IN-WITH-X and currently also accepts legacy X-Sign-In-With-X; both carry a base64-encoded JSON object containing the wallet address, SIWE/SIWX message, signature, timestamp, and Base chain identity (8453, "8453", or "eip155:8453").
When a 402 response includes siwxChallenge, build the SIWE message from that challenge. If no challenge is available, use these Base/EVM SIWE fields: domain: "outerface.venice.ai", address: <Base wallet address>, statement: "Sign in to Venice API", uri: "https://outerface.venice.ai", version: "1", chainId: 8453, nonce: <random 16-character hex string>, issuedAt: <current ISO 8601 timestamp>, and expirationTime: <ISO 8601 timestamp about 10 minutes later>. Serialize the EIP-4361 prepareMessage fields in this order and keep the resulting string byte-identical from Base MCP personal_sign through SIGN-IN-WITH-X construction: domain, address, statement, uri, version, chainId, nonce, issuedAt, expirationTime.
For Base/EVM wallets, construct the sign-in header value as base64-encoded UTF-8 JSON with these keys: address (Base wallet address), message (the exact SIWE string signed by Base MCP), signature (the personal_sign result), timestamp (Unix milliseconds from the same flow), and chainId (8453 as a number unless Venice returns a different challenge format). Send it as SIGN-IN-WITH-X, falling back to X-Sign-In-With-X only if the current Venice endpoint rejects the current header name. Use a fresh nonce and timestamp per request flow, keep expirationTime short-lived, and do not reserialize or normalize the SIWE message after signing.
Base x402 top-ups use USDC on Base. POST /x402/top-up without X-402-Payment returns a 402 response with an accepts array. Pick a Base payment option from that array and sign/pay exactly those returned fields. Do not hardcode payTo, asset, or amount from examples.
| Capability | HTTP-capable harnesses (Cursor, Codex, Claude Code, etc.) | Chat-only / no direct HTTP |
|---|---|---|
Public discovery (GET /models) | Use the harness HTTP tool first. | Use Base MCP web_request if api.venice.ai is allowlisted; otherwise ask the user to open/paste the GET URL. |
| API-key inference | Use the harness HTTP tool with Authorization: Bearer .... | Use Base MCP web_request if api.venice.ai is allowlisted and a secret can be provided safely; otherwise stop and ask the user to use an HTTP-capable harness or Venice UI. |
| x402 sign-in header | Use Base MCP get_wallets, then Base MCP sign, then the harness HTTP tool with SIGN-IN-WITH-X. | Same Base MCP sign path; use web_request for Venice calls only if the host is allowlisted and custom headers are supported. Otherwise stop and ask the user to use an HTTP-capable harness or an API key. |
| x402 balance / transactions | Build a fresh SIGN-IN-WITH-X header, then GET /x402/balance/{walletAddress} or GET /x402/transactions/{walletAddress}. | Same, through web_request only when it can send SIGN-IN-WITH-X; the user-paste GET fallback is not usable because the endpoint requires a custom auth header. |
| x402 top-up with Base USDC | Use Venice POST /x402/top-up for payment requirements, then the Base MCP x402 payment tool advertised by the MCP catalog. | Same only if web_request can make POST calls and the x402 payment tool is exposed. Otherwise stop and tell the user to top up in Venice, use an API key, or switch to an HTTP-capable harness. |
| Streaming responses | Use harness HTTP streaming support if available. | Prefer non-streaming requests; do not try to simulate SSE through web_request unless the tool explicitly supports streaming. |
Base URL: https://api.venice.ai/api/v1
Public discovery endpoints such as GET /models return 200 without auth. For paid endpoints, use Authorization: Bearer <VENICE_API_KEY> for API-key auth or SIGN-IN-WITH-X: <base64 payload> for x402 wallet auth. Most paid inference endpoints accept either auth method and return 402 when balance is insufficient.
GET /models?type=<type>
Lists available models. type can be text, image, tts, asr, embedding, video, music, upscale, inpaint, code, or all. Response includes model IDs, capabilities, constraints, privacy mode, context length, and pricing metadata.
POST /chat/completions
OpenAI-compatible chat endpoint. Supports text plus compatible multimodal inputs (image_url, input_audio, video_url, and file blocks), tools/function calling, streaming, reasoning fields, and Venice-specific venice_parameters.
Typical request:
{
"model": "zai-org-glm-5-1",
"messages": [{ "role": "user", "content": "Hello from Venice." }],
"venice_parameters": {
"enable_web_search": "auto",
"enable_web_citations": true
}
}POST /responses
OpenAI-compatible Responses API route for typed output blocks. Use when the caller specifically asks for the Responses API or when a client already expects the /responses shape.
POST /image/generate
Venice-native text-to-image generation. Useful when the user asks for Venice-specific image controls such as style_preset, aspect_ratio, resolution, cfg_scale, seed, variants, safe_mode, or watermark.
POST /images/generations
OpenAI-compatible image generation endpoint. Use when an existing OpenAI client or prompt expects the /images/generations shape.
Other image endpoints exposed by Venice include /image/upscale, /image/edit, /image/multi-edit, /image/background-remove, and GET /image/styles.
POST /audio/speech
Text-to-speech. Common fields include input, model, voice, response_format, speed, language, and streaming. Response is binary audio such as MP3, WAV, FLAC, OPUS, AAC, or PCM depending on response_format.
POST /audio/transcriptions
Speech-to-text for uploaded audio.
POST /audio/queue, POST /audio/retrieve, POST /audio/complete
Async and complete music/audio generation routes.
POST /video/queue, POST /video/retrieve, POST /video/complete, POST /video/transcriptions
Async and complete video generation/transcription routes. Use queue/retrieve for long-running jobs unless the user specifically wants a synchronous complete call.
POST /embeddings
Generate vector embeddings. Use GET /models?type=embedding first when the user did not specify a model.
GET /x402/balance/{walletAddress}
Requires SIGN-IN-WITH-X for the same wallet. Response includes balanceUsd, canConsume, minimumTopUpUsd, suggestedTopUpUsd, and optional diemBalanceUsd.
POST /x402/top-up
Call with no payment header to get 402 payment requirements. Read the latest PAYMENT-REQUIRED header, or the parsed 402 response body if that is how the current HTTP tool exposes it, and choose the returned Base USDC option from its accepts array. Pay through the Base MCP x402 payment tool if exposed. Retry with the signed X-402-Payment header if the Base MCP tool returns one for the agent to submit.
GET /x402/transactions/{walletAddress}?limit=<n>&offset=<n>
Requires SIGN-IN-WITH-X for the same wallet. Use to inspect ledger entries such as TOP_UP, CHARGE, and REFUND.
GET /models?type=<needed type> and choose a model that matches the requested modality and capabilities.venice_parameters or the endpoint’s documented native fields.Authorization: Bearer <VENICE_API_KEY>.get_wallets and use baseAccount.address.siwxChallenge returned by a Venice 402 response when available.sign with type: "personal_sign" and the exact message string.../references/approval-mode.md.SIGN-IN-WITH-X as base64 JSON containing the wallet address, exact signed message, signature, current timestamp, and Base chain identity.GET /x402/balance/{walletAddress}. If canConsume is false or the balance is too low, run the top-up flow before inference.SIGN-IN-WITH-X.POST /x402/top-up without X-402-Payment to retrieve the current accepts array.network to Base / eip155:8453 and asset to the returned USDC asset.amount, payTo, asset, network, and x402 version/metadata. If no such Base MCP payment tool is exposed, stop and ask the user to top up through Venice or switch to an API key.GET /x402/balance/{walletAddress} with a fresh SIGN-IN-WITH-X header.This plugin has three submission paths:
sign signs the exact SIWX/SIWE message. Map the signed response into the SIGN-IN-WITH-X header; do not sign or alter a different message afterward.accepts entry exactly. Follow ../references/approval-mode.md for the returned approval URL and request ID.Do not use send_calls to hand-roll x402 payments unless the Base MCP tool catalog explicitly documents that as the supported x402 payment path. Do not ask for or use a private key.
Use Venice to summarize this with a private model
GET /models?type=text and choose a suitable private text model.POST /chat/completions with the user’s text and any requested venice_parameters.Top up my Venice x402 balance with 5 USDC on Base
get_wallets and prepare a fresh SIGN-IN-WITH-X header through Base MCP sign.POST /x402/top-up to get the current payment requirements.GET /x402/balance/{walletAddress}.Use my Base wallet to ask Venice zai-org-glm-5-1 a question
SIGN-IN-WITH-X with Base MCP sign.GET /x402/balance/{walletAddress}.canConsume is true, call POST /chat/completions with the requested model and prompt.Generate an image with Venice using a cinematic style
GET /models?type=image or GET /image/styles./image/generate for Venice-native controls like style_preset, aspect_ratio, resolution, seed, or variants.https://api.venice.ai/api/v1.api.venice.ai must be allowlisted for Base MCP web_request on chat-only surfaces.GET /models rather than hardcoding model IDs when the user asks for “best”, “private”, “vision”, “image”, “TTS”, or another capability-based choice.X-Balance-Remaining and X-Request-ID.0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, but the x402 top-up flow must use the asset returned in the latest Venice accepts entry.