API and MCP

Give your own agent a desk with walls

Install the Troya MCP server with one command, or call the REST API directly. Read tools work for everyone. Add an API token and the same server can act through your Agent Wallet, but never past its caps.

$npx -y @troyaagent/mcp

Launch app

01 / Install

One command, any client

The MCP server runs on your own machine over stdio and stores no keys. It forwards each tool call to Troya, where your policy is checked before anything happens. Leave the token out and you get the read tools only.

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "troya": {
      "command": "npx",
      "args": ["-y", "{{pkg}}"],
      "env": {
        "TROYA_BASE_URL": "{{base}}",
        "TROYA_API_KEY": ""
      }
    }
  }
}

Cursor · .cursor/mcp.json

{
  "mcpServers": {
    "troya": {
      "command": "npx",
      "args": ["-y", "{{pkg}}"],
      "env": { "TROYA_BASE_URL": "{{base}}" }
    }
  }
}

Claude Code · terminal

# read tools only
claude mcp add troya -e TROYA_BASE_URL={{base}} -- npx -y {{pkg}}

# with Agent Wallet tools (create the token in the app: Agent → Wallet → API tokens)
claude mcp add troya -e TROYA_BASE_URL={{base}} -e TROYA_API_KEY=<your-token> -- npx -y {{pkg}}

Execution over MCP starts in dry-run: orders are prepared and checked, then reported instead of sent. Switching dry-run off is a deliberate setting per API token in the app.

02 / Choose an interface

Three doors, one set of walls

01 · READ TOOLS

No token needed

Hyperliquid perps, the Elysium token board, swap quotes on Elysium and HyperEVM, token health checks and the daily brief. Nothing in this set can move funds.

02 · AGENT WALLET TOOLS

With an API token

Add a token and the server can also swap, bridge, trade perps and launch tokens from your Agent Wallet, each call passing Troya Gate and your caps first.

03 · REST

Plain HTTP

Public GET routes for markets and quotes. POST routes for execution need an x-api-key header and an Idempotency-Key, so retries are safe.

03 / REST

HTTP for your own code

Base URL /agent/api. Responses are JSON. Every call made with a token lands in the same journal you see in the app.

Method	Route	What it returns	Auth
GET	`/market/elysium`	Elysium token board. Query: `q`, `launchpad`, `sort`, `dir`, `limit`, `offset`.	Public
GET	`/market/elysium/token?address=`	One Elysium token: price in HYPE, volume, holders, pool and launchpad.	Public
GET	`/market/hl`	Hyperliquid perp markets with price, 24h change, funding, open interest and volume.	Public
GET	`/tools`	The tool list with each tool's tier and input schema.	Public
POST	`/tools/:name`	Run a tool. Read tools work without a token; prepare and execute tools need one.	`x-api-key` + `Idempotency-Key`

Read · top Elysium tokens by volume

curl -s "{{base}}/market/elysium?sort=volume&limit=10"

Read · Hyperliquid markets

curl -s "{{base}}/market/hl"

Execute · prepare, then execute with the confirmationId

# 1) prepare: Troya Gate runs, you get a one-time confirmationId (valid 120 s)
curl -s -X POST "{{base}}/tools/prepare_order" \
  -H "content-type: application/json" \
  -H "x-api-key: $TROYA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"venue":"hyperliquid","coin":"BTC","side":"long","sizeUsd":50,"leverage":3}'

# 2) execute: only the confirmationId is accepted; dry-run unless you turned it off
curl -s -X POST "{{base}}/tools/execute_intent" \
  -H "content-type: application/json" \
  -H "x-api-key: $TROYA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"confirmationId":"<from step 1>"}'

04 / Tool tiers

What each tier is allowed to do

Tier 1 · Read

Look only: markets, quotes, balances, positions, token health, policy. Safe to call in a loop.

READ

Tier 2 · Prepare

Simulate an order and run Troya Gate. Returns a confirmationId that expires after 120 seconds and is bound to a hash of the exact parameters.

PREPARE

Tier 3 · Execute

Takes only a confirmationId, re-reads the policy and sends the order from the Agent Wallet. Dry-run by default; blocked entirely while Pause or the operator kill switch is on.

EXECUTE

Create a token, then connect.

Open the Troya app Risk Controls