https://vexthium.com/api/mcp

Vexthium · Reference · Developers

Developer guide

Vexthium speaks HTTP. Any code that can POST JSON reaches the same tools an AI client uses.

Protocol
JSON-RPC 2.0
Also
REST
Signing
Your key
Tools
36

Pick a path

What you buildEntry pointReason
An AI chat or coding agentThe MCP endpointThe client finds the tools and their schemas on its own.
A script or backend jobREST routesOne POST for each tool, with the JSON-RPC wrapper left out.
An agent that holds a walletMCP or REST with local signingVexthium prepares, your code signs, Vexthium broadcasts.
An app for end usersMCP and the approval pageEach 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.

initialize
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"}}}
tools/call
{"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.

TypeScript helper
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.

  1. 01Call a prepare_* tool with your address in from. Check previews[].risk and halt on any flag you did not plan for.
  2. 02Pick up each item in unsignedTransactions. Nonce and gas come filled in.
  3. 03Sign with the library you prefer. Mainnet is chain ID 4663.
  4. 04Pass the raw signed hex to send_signed_transaction. Vexthium rejects a transaction signed for another chain.
  5. 05Poll wait_for_transaction with the hash until it reports confirmed or reverted.
viem
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");
}

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" }
  ]
}
  • v is 1, and chainId is 4663 or 46630.
  • txs carries one to ten steps. A deployment leaves out to.
  • value and gas are decimal strings, and nonce is 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, sellAmount and all balances are decimal strings. Parse them with a big-integer type.
  • Human amounts say so. amount on 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 ETH wherever a token goes. Balance changes show it as 0xeeee…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.

ErrorRetryWhat to do
rate_limitedYesWait up to 60 seconds. Add an agent key if it keeps happening.
upstream_errorYesBack off exponentially and try again. The RPC node or the explorer failed upstream of your call.
invalid_inputNoCorrect the argument the message names.
unauthorized / forbiddenNoSwap the key, or use one that holds the needed scope.
unsupported / not_configuredNoThis 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.

VariableSwitches on
SUPABASE_URLAgent keys, rate limits and usage stats. With no database the instance runs open, with no limits applied.
SUPABASE_SERVICE_ROLE_KEYDatabase access from the server. Keep it out of any browser bundle.
VEXTHIUM_SECRET32 characters or more. Signs management tokens and salts caller hashes.
NEXT_PUBLIC_APP_URLThe public origin written into approval links.
RHC_MAINNET_RPC_URLYour own mainnet RPC. The public endpoint, with its rate limit, is the fallback.
RHC_TESTNET_RPC_URLYour own development network RPC.
BLOCKSCOUT_API_KEYMainnet transaction history, ABIs and verification.

Before mainnet

  • Set chainId on every call where the chain matters, even with mainnet as the default.
  • Halt on each danger flag, and send each warning for review by a person or by policy.
  • Count a transaction as done once wait_for_transaction returns confirmed.
  • 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.