Sign in
DocsAPI

Build an agent on the API

How an AI agent finds the API, authenticates, and trades safely — llms.txt, the OpenAPI document, MCP, and the dry-run-then-commit loop.

Everything an agent needs is public and machine-readable. This page is the map; the other API pages hold the details, and each of them is also plain Markdown at its address plus .md.

Find the API#

WhatWhere
agents.txthttp://localhost:3000/agents.txt — the one-page manifest: every address below, how a key works, the safety rails, what an agent may fetch here and the rules, as Field: value lines
llms.txthttp://localhost:3000/llms.txt — a short index of every docs page with a one-line summary, API pages first
llms-full.txthttp://localhost:3000/llms-full.txt — every docs page in one Markdown file
Any page as Markdownadd .md to its address, e.g. http://localhost:3000/docs/api/trading.md
API indexGET https://evm.vortexdeployer.com/evm/api/v1 — a JSON object with every address in this table, no key needed
OpenAPI 3.1https://evm.vortexdeployer.com/evm/api/v1/openapi.json — every REST operation with its operationId, parameters, body schema and the scope it needs (x-scope)
MCP serverhttps://evm.vortexdeployer.com/evm/api/v1/mcp — the same operations as tools (MCP for AI agents)
Live streamswss://evm.vortexdeployer.com/evm/ws — trades, PnL and balances as they happen (Live streams)

An agent handed nothing but the REST base can read the index, fetch the OpenAPI document and start calling.

Authenticate#

A person creates the key in the app — open API in the header — and hands it to the agent. There is no sign-up or token exchange for agents, and a key works until its owner revokes it. (The one exception: an OAuth-only MCP client like a Claude.ai custom connector goes through the OAuth flow itself, which ends in an access token bound to a key the owner picked — same rules from then on.)

  • REST and MCP: Authorization: Bearer vd_… on every request (or a vdo_… OAuth access token bound to a key).
  • Streams: the key in the token field of the subscribe message.
  • GET /me tells the agent what its key may do: scopes, per-trade and daily caps, the wallet list, and whether it is sandboxed. Read it first and plan within it instead of discovering refusals one by one.

Stay safe#

The agent acts as the key's owner with real funds. The API is built so that a careful agent cannot do harm by accident:

  • Ask for the smallest key. read for research and reporting; trade with maxSolPerTrade and dailySolCap for trading; launch only for an agent that launches. See API overview & keys.
  • Dry-run first. POST /launch is a dry run unless dryRun is false; buy, sell and trade/batch take dryRun: true. A dry run runs the whole route and reports what would happen without sending anything.
  • Send an Idempotency-Key on every buy, sell, batch and launch. When a connection drops or a call times out, retry with the same key and the same body: you get the original answer, never a second trade. 409 operation_pending means the first attempt is still settling; wait and retry the same key. Details in Limits, retries & errors.
  • Expect long calls to be cut. A launch or a synchronous batch can run longer than the edge keeps a connection open (about 100 seconds). The trade continues on the server; retry with the same Idempotency-Key to collect the result. For anything slow, prefer the delayed batch, which returns a task id at once.
  • Read the headers. X-RateLimit-Remaining and X-RateLimit-Reset say when to slow down; a 429 carries retryAfterSeconds.
  • Switch on code, not on error. Every refusal has a stable machine-readable code; the human text changes.
Amounts

SOL amounts are decimal strings in the API ("0.25"); token amounts are base units (amountRaw) or a percentage of the bag on sells. Never guess decimals — read them from the wallet or token-balance answers.

A loop that works#

  1. GET /me — what may this key do?
  2. GET /wallets and GET /wallets/balances — which wallet, with what?
  3. For a launch, GET /launchpads and GET /launchpads/:launchpad/quotes — which launchpad, quoted in what? Copy the quoteToken and pairToken an entry gives you.
  4. Dry-run the trade (dryRun: true) and show the person the expected result.
  5. Commit with a fresh Idempotency-Key; on any error other than a refusal, retry the same key.
  6. Subscribe to txs:<mint> and pnl:<mint> on the socket to follow the outcome instead of polling.

MCP or REST?#

  • MCP for assistants (Claude, Cursor, Windsurf and others): tools arrive with descriptions, schemas and a readOnlyHint, so a client that asks before non-read calls asks before every trade. Nothing to install.
  • REST for your own code: the OpenAPI document generates a typed client in any language.
  • Streams are a WebSocket in both cases — MCP tools do not stream.