AI Agent Setup

Use AI coding agents to build on the Metafide API. This guide covers setup for popular tools like Claude Code, Cursor, OpenClaw, and others.

Overview

AI agents can help you rapidly prototype trading bots, build dashboards, and integrate SpotOn predictions into your applications. To get started, your agent needs:

A Metafide API key
Context about the API (this documentation)
A project setup with an HTTP client

Get Your API Key

Before configuring your agent, generate an API key:

Go to spoton.metafide.io/wallet
Connect your wallet
Generate a new API key
Store it in an environment variable:

macOS / Linux:

export METAFIDE_API_KEY="metafide_your_key_here"

Windows (PowerShell):

$env:METAFIDE_API_KEY="metafide_your_key_here"

To set permanently on Windows, use System Properties → Environment Variables, or run setx METAFIDE_API_KEY "metafide_your_key_here" (requires new terminal to take effect).

warning

Never paste your API key directly into agent chat. Use environment variables or a .env file (and make sure .env is in your .gitignore).

Environment variable naming

The MCP server uses METAFIDE_USER_ADDRESS for your wallet address. Some older bot templates use METAFIDE_WALLET_ADDRESS. Both refer to the same value — your wallet address from the SpotOn wallet page.

Agent Configuration

SpotOn MCP Server

The fastest way to start running bots. Install the SpotOn MCP server and control your bot through natural conversation — no code required.

The MCP server gives your AI assistant 9 tools for checking prices, placing positions, running bot cycles, and managing configuration. Works with Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, and Windsurf.

Prerequisites: Node.js 18+ (node --version to check). On Windows, close and reopen your terminal after installing Node.

Install and set up:

npm install -g metafide-spoton-mcp

metafide-spoton-setup

The setup wizard prompts for your API key and wallet address, auto-detects installed AI tools, and configures them. Restart your AI tool after setup.

Windows troubleshooting

If npm install -g fails or metafide-spoton-setup isn't found:

Run as Administrator — Right-click your terminal and select "Run as administrator"
Check your PATH — Run npm config get prefix and verify that path is in your system PATH
Try npx — Run npx metafide-spoton-setup instead of installing globally
Permission errors — Run npm config set prefix %APPDATA%\npm to use a user-writable directory

Try it

After setup, open your AI tool and say: "What's my balance?" If you see your USDC balance, you're connected.

Available tools (9):

Tool	What it does
`get_balance`	Check your current USDC balance
`get_live_price`	Get the current BTC price
`get_game_status`	See active positions, projected winnings, and streaks
`get_spot_game`	Check if a game is active and accepting positions
`place_position`	Place a prediction at a specific price and stake
`run_bot_cycle`	Run one full cycle — check game, generate positions, submit
`configure_strategy`	Change settings: network, interval, max positions, price ranges
`get_config`	View current configuration
`get_results`	Get historical game results: winnings, returns, closing prices

Talk naturally — no tool names needed:

You: "What's BTC at right now?"
AI:  "$68,245.12"

You: "Place a position at 68,250 with 2 USDC"
AI:  "Position placed on game 548102."

You: "Run a bot cycle"
AI:  "10 positions placed. 0 failed."

You: "Switch to 1-hour games and set max positions to 5"
AI:  "Interval: 3600. Max positions: 5."

Mainnet safety: When placing positions on mainnet, the bot always asks for confirmation before executing. Testnet is the default — no risk while you learn.

Manual setup (if wizard didn't detect your tool)

Claude Desktop — Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Or use Settings → Edit Config File in Claude Desktop

{
  "mcpServers": {
    "metafide-spoton": {
      "command": "metafide-spoton-mcp",
      "env": {
        "METAFIDE_API_KEY": "your_api_key_here",
        "METAFIDE_USER_ADDRESS": "your_wallet_address_here"
      }
    }
  }
}

Claude Code CLI:

claude mcp add metafide-spoton -- env METAFIDE_API_KEY=your_key METAFIDE_USER_ADDRESS=your_wallet metafide-spoton-mcp

ChatGPT Desktop — Add to MCP config:

macOS: ~/.config/openai/mcp.json
Windows: %APPDATA%\openai\mcp.json

Use the same JSON structure as Claude Desktop above.

Gemini CLI:

gemini mcp add metafide-spoton -- env METAFIDE_API_KEY=your_key METAFIDE_USER_ADDRESS=your_wallet metafide-spoton-mcp

Cursor / Windsurf — Add to .cursor/mcp.json or .windsurf/mcp.json in your project directory (not global). Use the same JSON structure as Claude Desktop above. These are project-level configs, so each project can have its own MCP setup.

Local clone (development):

git clone https://github.com/Metafide/spot-on.git
cd spot-on/mcp-server
npm install
npm run build

Then use "command": "node", "args": ["/path/to/spot-on/mcp-server/dist/src/index.js"] in your config.

warning

If you store MCP config files in a project directory (.cursor/mcp.json, .windsurf/mcp.json), add them to your .gitignore to avoid committing your API key.

Try the Intelligent Agent (Beta)

Want a bot that actually learns? The Spot-On Agent is an advanced MCP server that gets smarter every round. It tracks what works, adapts its strategy based on real results, and builds optimized position portfolios — while you steer through natural conversation.

What it adds over the bare-metal server:

Adaptive engine — learns which amounts, spreads, and position roles perform best, then shifts strategy automatically
Smart cycles — builds anchor/hedge portfolios instead of random placements
Performance tracking — persists results across sessions so the bot carries its learning forward
Play modes — start in bare-metal, graduate to collaborative (preview + discuss), then autonomous (hands-off)
Multi-account — run different strategies in parallel with isolated config and history
22 tools including preview, staggered placement, settlement tracking, and strategy notes

npm install -g metafide-spoton-agent-mcp@beta

metafide-spoton-agent-setup

Full docs and changelog: metafide-spoton-agent-mcp on npm

The sections below cover how to give AI coding agents raw API context for building custom bots from scratch.

Claude Code

Create a CLAUDE.md file in your project root to give Claude Code persistent context:

## Metafide API

- Base URL: https://api.metafide.io/v1/surge/games
- Auth: pass API key via `x-api-key` header (stored in METAFIDE_API_KEY env var)
- Docs: https://docs.metafide.io/docs/intro

### Endpoints
- GET /spot — get current and next game (params: asset, interval)
- GET /live-price — get live asset price (params: asset)
- GET /user-balance — get user balance (params: currency, network)
- GET /status — get active positions (params: asset, token, network, interval)
- POST /spot — create a prediction position

### Key Details
- Asset format: BTC_USDT
- Intervals: 60 (1 min), 3600 (1 hour), 86400 (24 hours)
- All timestamps are Unix milliseconds
- Prices are returned as strings
- Interval is passed as a query string (e.g. `?interval=60`) — the API accepts it as a number

Cursor

Add a .cursorrules file to your project root:

## Metafide API

- Base URL: https://api.metafide.io/v1/surge/games
- Auth: pass API key via `x-api-key` header (stored in METAFIDE_API_KEY env var)
- Docs: https://docs.metafide.io/docs/intro

### Endpoints
- GET /spot — get current and next game (params: asset, interval)
- GET /live-price — get live asset price (params: asset)
- GET /user-balance — get user balance (params: currency, network)
- GET /status — get active positions (params: asset, token, network, interval)
- POST /spot — create a prediction position

### Key Details
- Asset format: BTC_USDT
- Intervals: 60 (1 min), 3600 (1 hour), 86400 (24 hours)
- All timestamps are Unix milliseconds
- Prices are returned as strings
- Interval is passed as a query string (e.g. `?interval=60`) — the API accepts it as a number

OpenClaw & Other Agents

Most AI coding agents support a system prompt or project context file. Add the same API reference above to whichever context mechanism your agent uses (e.g. a project-level prompt, a pinned file, or a README).

Quickstart

Once your agent is configured, try these prompts to verify everything works:

1. Fetch the live BTC price

"Write a script that fetches the current BTC_USDT price from the Metafide API and prints it."

Expected output:

const response = await fetch(
  'https://api.metafide.io/v1/surge/games/live-price?asset=BTC_USDT',
  {
    headers: {
      'Accept': '*/*',
      'x-api-key': process.env.METAFIDE_API_KEY,
    },
  }
);
const data = await response.json();
console.log(`BTC price: $${data.value}`);

2. Check the current game

"Get the current live SpotOn game for BTC_USDT on the 1-minute interval."

3. Place a prediction

"Place a SpotOn prediction for the current BTC_USDT 1-minute game with a predicted price of 67000 and a stake of 5 USDC."

4. Monitor your position

"Check the status of my active SpotOn positions for BTC_USDT."

Tips

Start with read-only endpoints — Use GET /live-price, GET /spot, and GET /status before placing positions. When ready, use POST /spot to create a position (Create Position docs).
Let the agent iterate — If a request fails, paste the error back. Agents are good at self-correcting from API error messages.
Reference the docs — Point your agent at the Errors page when debugging. The error table covers all common failure modes.
Use the 1-minute interval for testing — Games cycle quickly, so you get fast feedback loops.

API reference

All endpoints are under https://api.metafide.io/v1/surge/games/. For example:

GET /spot → https://api.metafide.io/v1/surge/games/spot
POST /spot → same URL, different method

See the Spot Games and Create Position docs for full request/response details.

Overview​

Get Your API Key​

Agent Configuration​

SpotOn MCP Server​

Claude Code​

Cursor​

OpenClaw & Other Agents​

Quickstart​

1. Fetch the live BTC price​

2. Check the current game​

3. Place a prediction​

4. Monitor your position​

Tips​