· Channels — how you connect

REST API

Call AlgoVault over plain HTTP, two ways. Keyless x402 pay-per-call settles USDC on Base per request — no signup, no API key. Or authenticate with an API key against the /api/* endpoints. Same composite BUY / SELL / HOLD verdicts, callable from any language, cron job, or serverless function.

When to use REST API vs the other channels

Use the REST API for HTTP access without an MCP client — a serverless function, a cron job, a non-MCP agent runtime. Keyless x402 needs no account and settles per call; API-key access suits steady volume. It is a plain request/response API, not the MCP protocol — if your framework speaks MCP, prefer the MCP server for typed tool discovery.

Connect

x402 Pay-Per-Call (USDC on Base)

No signup. No API key. No billing. Your agent pays per HTTP call with USDC on Base — the payment receipt is the credential. Works with any x402-compatible client or wallet.

How it works

Call the endpoint — your agent POSTs to an x402 route (e.g. /x402/get_trade_call) with no payment attached.
Receive a 402 quote — the server replies 402 Payment Required with the price, asset (USDC), network (Base), and recipient address.
Sign & retry — your x402 client signs an ERC-3009 transferWithAuthorization and retries with the signed X-PAYMENT header. The facilitator submits it on-chain, so your agent pays no gas.
Get your verdict — the server verifies the signature and returns the result immediately; settlement confirms on Base in ~2 seconds.

Quick start (TypeScript)

The official x402-fetch client wraps fetch and runs the 402 → sign → retry handshake for you. Your wallet just needs USDC on Base.

// npm i x402-fetch viem
import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const wallet  = createWalletClient({ account, chain: base, transport: http() });
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

// Pays automatically on the 402, then returns the verdict.
// content-type: set it EXACTLY once. x402-fetch wraps raw fetch, which would send a string
// body as text/plain — so here you must set it. Circle's GatewayClient.pay() is the opposite:
// it sets Content-Type itself, so passing your own merges into "application/json,
// application/json" and the server replies 400 invalid_content_type (you are not charged).
const res = await fetchWithPay("https://api.algovault.com/x402/get_trade_call", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ coin: "BTC", timeframe: "1h" }),
});

const verdict = await res.json();
console.log(verdict.call, verdict.confidence); // e.g. "BUY" 72

Set `content-type` exactly once

The two common x402 clients have opposite requirements, and getting it wrong produces the same 400 invalid_content_type after your payment has already verified (you are not charged):

x402-fetch wraps raw fetch, which sends a string body as text/plain — so you must pass content-type: application/json yourself, as above.
Circle's GatewayClient.pay() (the Circle Gateway rail advertised on every 402) already sets Content-Type — so you must not. Adding your own leaves both capitalisations in the options object; fetch then merges them into application/json, application/json, which no JSON parser accepts. Pass body as a plain object and omit headers entirely.

Endpoints & pricing

Endpoint	Price / call
`POST /x402/get_trade_call`	$0.02 (HFT 1m–5m: up to $0.05)
`POST /x402/scan_funding_arb`	$0.01
`POST /x402/get_market_regime`	$0.02

Base URL https://api.algovault.com.

New to x402? The open protocol spec and client libraries (x402-fetch, x402-axios) live at x402.org.

Full reference in the docs →

HTTP API (search & chat)

Both tools also expose plain HTTP endpoints for non-MCP consumers. Send a JSON body, read a JSON response — no JSON-RPC envelope, no dual Accept header, no SSE to unwrap.

Trade calls are served over POST /mcp and the /x402/* routes. There is no separate /api/trade-call endpoint.

Endpoint	Body	Cache
`POST /api/search`	`{"query": "string", "limit": 10}`	public, max-age=300
`POST /api/chat`	`{"question": "string", "model": "..."}`	no-store (per-user)

Error contract: INVALID_QUERY / QUERY_TOO_SHORT / QUERY_TOO_LONG / INVALID_QUESTION / QUESTION_TOO_SHORT / QUESTION_TOO_LONG / INVALID_MODEL / CHAT_QUOTA_EXHAUSTED / INTERNAL_ERROR. All return JSON {"code": "...", "message": "..."}.

Full REST API guide →

Full reference in the docs →

Tool coverage

Every publicly-listed tool reachable through REST API (equities are held from public listings):

Frequently asked questions

Is there a free way to call the REST API?

Yes — keyless x402 pay-per-call needs no signup or API key; your agent settles USDC on Base per request. API-key access is the alternative for steady volume.

What's the difference between the x402 and /api endpoints?

x402 is keyless pay-per-call (USDC on Base) for the signal tools; the /api/* endpoints (for example /api/search and /api/chat) use an API key. Both are plain HTTP.

Do I need the MCP handshake for the REST API?

No. The REST API is a plain request/response HTTP call — no initialize or session handshake. That handshake belongs to the MCP-over-HTTP transport, not to this channel.

What format are responses in?

JSON. Every response carries the composite verdict plus an _algovault metadata block.

Should I use an API key or x402?

Two rails, pick one. An API key bills a monthly plan and is sent as an Authorization: Bearer header. x402 pays per call in USDC on Base and needs no account. Choose a key for steady volume, x402 for one-off agent calls. Sign up at https://algovault.com/signup, or send an x402 request and let your wallet settle it.

What are the tiers and limits?

Free gives 200 calls a month. Starter gives 10,000 for $9.99 a month. Pro gives 100,000 for $49. Quota is counted per call, regardless of verdict. Read the _algovault.quota block on any response for your live remaining count.

How do I know my API key is being applied?

Read _algovault.auth on any response. An outcome of OK, with your paid tier beside it, means the key applied. A paid key reporting tier "free" was NOT applied — the request was served as anonymous. Check the header name and the Bearer prefix, then call again and re-read the block.

What do the error codes mean?

Two shapes, so check both. Code -32602 arrives as HTTP 200 with result.isError set and the code inside the text. Codes -32003 and -32004 arrive as a JSON-RPC error object instead. Check error first, then result.isError. Read the full table at https://algovault.com/docs#tools-errors.

Which tools work over REST, and which need MCP?

REST reaches get_trade_call, get_market_regime, scan_funding_arb, and scan_trade_calls. MCP additionally reaches chat_knowledge and search_knowledge. Use REST for the signal tools from any language; use MCP when you also want the knowledge tools. Full reference at https://algovault.com/docs#rest-api.

Explore the tools →