Pick a path
| What you build | Entry point | Reason |
|---|---|---|
| An AI chat or coding agent | The MCP endpoint | The client finds the tools and their schemas on its own. |
| A script or backend job | REST routes | One POST for each tool, with the JSON-RPC wrapper left out. |
| An agent that holds a wallet | MCP or REST with local signing | Vexthium prepares, your code signs, Vexthium broadcasts. |
| An app for end users | MCP and the approval page | Each user reviews and signs in their own wallet. |
Every path runs through one relay, so tools, budgets, keys and error codes are identical across all four.
JSON-RPC calls
Transport is Streamable HTTP with no session state, so there is no connection to keep open. The server answers initialize, and tools/call works without it.
POST https://vexthium.com/api/mcp
content-type: application/json
accept: application/json, text/event-stream
{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"2025-06-18","capabilities":{},
"clientInfo":{"name":"my-app","version":"1.0.0"}}}{"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"simulate_transaction",
"arguments":{"from":"0x…","to":"0x…","valueWei":"1000000000000000"}}}The payload sits in result.content[0].text as a JSON string, so parse it. If result.isError is true, that text is a plain code: message line.
async function callTool(name: string, args: unknown, key?: string) {
const res = await fetch("https://vexthium.com/api/mcp", {
method: "POST",
headers: {
"content-type": "application/json",
accept: "application/json, text/event-stream",
...(key ? { authorization: `Bearer ${key}` } : {}),
},
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
});
const body = await res.json();
const text: string = body.result?.content?.[0]?.text ?? "";
if (!res.ok || body.result?.isError) throw new Error(text || body.error?.message);
return JSON.parse(text);
}REST calls
Each tool has its own route. Post the arguments as the body and read the shared envelope back.
curl -s https://vexthium.com/api/tools/get_wallet_info \
-H 'content-type: application/json' \
-H 'authorization: Bearer vxm_…' \
-d '{"address":"0x…"}'
{ "ok": true, "data": { … } }
{ "ok": false, "error": { "code": "invalid_input", "message": "address: Invalid address" } }Call GET /api/tools once for the name, scope and JSON Schema of every tool. Build your types or validators from that catalog; it is the source of truth and lists 36 tools today.
Local signing
Vexthium handles every step around the signature and leaves the signature to you.
- 01Call a
prepare_*tool with your address infrom. Checkpreviews[].riskand halt on any flag you did not plan for. - 02Pick up each item in
unsignedTransactions. Nonce and gas come filled in. - 03Sign with the library you prefer. Mainnet is chain ID 4663.
- 04Pass the raw signed hex to
send_signed_transaction. Vexthium rejects a transaction signed for another chain. - 05Poll
wait_for_transactionwith the hash until it reportsconfirmedorreverted.
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.AGENT_KEY as `0x${string}`);
const prepared = await callTool("prepare_token_transfer", {
from: account.address, token: "ETH", to: "0x…", amount: "0.01",
});
if (prepared.previews.some((p) => p.risk.some((r) => r.level === "danger"))) throw new Error("danger flag, stopping");
for (const tx of prepared.unsignedTransactions) {
const signed = await account.signTransaction({
chainId: prepared.chainId, to: tx.to, data: tx.data, value: BigInt(tx.value),
nonce: tx.nonce, gas: BigInt(tx.gas), /* add the current fee fields */
});
const { hash } = await callTool("send_signed_transaction", { signedTransaction: signed });
let receipt;
do receipt = await callTool("wait_for_transaction", { hash, timeoutSeconds: 60 });
while (receipt.status === "pending");
if (receipt.status !== "confirmed") throw new Error("transaction reverted");
}Approval link payload
The self-contained form of an approval link is https://vexthium.com/sign#<payload>, where the payload is unpadded base64url JSON:
{
"v": 1,
"chainId": 4663,
"title": "Send 0.01 ETH",
"txs": [
{ "from": "0x…", "to": "0x…", "data": "0x", "value": "10000000000000000", "nonce": 12, "gas": "21000" }
]
}vis 1, andchainIdis 4663 or 46630.txscarries one to ten steps. A deployment leaves outto.valueandgasare decimal strings, andnonceis an integer.- The page rejects a payload that breaks any of these rules. It uses no query string, so loading the page sends no transaction detail to the server.
Hand the link to the user exactly as returned. Some chat surfaces remove URL fragments; on those, show the link as plain text the user can copy.
Amounts and addresses
- Base units travel as strings.
valueWei,sellAmountand all balances are decimal strings. Parse them with a big-integer type. - Human amounts say so.
amounton transfer, approval and deposit tools is a decimal string like"1.5", and Vexthium applies the token's decimals. - Addresses. Any valid 20-byte hex address works as input. Output addresses are checksummed.
- Native ETH. Write
ETHwherever a token goes. Balance changes show it as0xeeee…eeee.
Budgets and retries
Open access allows 120 calls a minute, 10 of them heavy. An agent key allows 600 and 60. The window slides, so a burst frees up over the next minute.
| Error | Retry | What to do |
|---|---|---|
rate_limited | Yes | Wait up to 60 seconds. Add an agent key if it keeps happening. |
upstream_error | Yes | Back off exponentially and try again. The RPC node or the explorer failed upstream of your call. |
invalid_input | No | Correct the argument the message names. |
unauthorized / forbidden | No | Swap the key, or use one that holds the needed scope. |
unsupported / not_configured | No | This chain or this instance lacks the capability. |
Repeat read tools as often as you like. Prepare tools repeat cleanly too: two prepares give two unsigned transactions on the same nonce, and only the signed one lands. send_signed_transaction repeats cleanly with the same signed hex, since each nonce lands once.
Self-hosting
Vexthium is a Next.js app. It starts with zero configuration on the public RPC, and each variable here switches on one capability. GET /api/health responds once the app is running.
| Variable | Switches on |
|---|---|
SUPABASE_URL | Agent keys, rate limits and usage stats. With no database the instance runs open, with no limits applied. |
SUPABASE_SERVICE_ROLE_KEY | Database access from the server. Keep it out of any browser bundle. |
VEXTHIUM_SECRET | 32 characters or more. Signs management tokens and salts caller hashes. |
NEXT_PUBLIC_APP_URL | The public origin written into approval links. |
RHC_MAINNET_RPC_URL | Your own mainnet RPC. The public endpoint, with its rate limit, is the fallback. |
RHC_TESTNET_RPC_URL | Your own development network RPC. |
BLOCKSCOUT_API_KEY | Mainnet transaction history, ABIs and verification. |
Before mainnet
- Set
chainIdon every call where the chain matters, even with mainnet as the default. - Halt on each
dangerflag, and send eachwarningfor review by a person or by policy. - Count a transaction as done once
wait_for_transactionreturnsconfirmed. - Give each key only the scopes it uses. A read-only dashboard can skip
prepare. - Keep a revocation path ready for an exposed key:
DELETE /api/keys/me. - Run the full flow once on the development network with
chainId: 46630.
Every parameter of every tool is listed in the tool index.
Reporting an issue
Send the tool name, the arguments with any key stripped, the error text and the call time. Vexthium logs each call's tool, status, duration and error code, and those four details locate it.