Running Bots

There are two ways to run automated bots on SpotOn: the MCP server (conversational, no code) or a custom HTTP bot (full control, write your own code).

Quick Comparison

	MCP Server	Custom HTTP Bot
Setup	npm install + setup wizard (2 min)	Clone repo, edit config, write code
How you interact	Talk to your AI assistant in plain English	Run a script in your terminal
Code required	None	JavaScript, Python, or any HTTP client
Strategy	Configure through conversation or config files	Write your own logic
Stays running	As long as your AI tool is open	Must keep terminal/process running (use screen, tmux, or a server)
Error handling	Built-in with retry logic	You handle it
Learning	Agent version tracks performance and adapts	You build your own analytics
Customization	9 tools, configurable params	Unlimited — full API access
Best for	Getting started, non-technical users, quick testing	Power users, custom strategies, production bots

MCP Server (Recommended to Start)

Install the MCP server and control your bot through conversation with Claude, ChatGPT, Gemini, or Cursor. No code required.

npm install -g metafide-spoton-mcp
metafide-spoton-setup

Then open your AI tool and say: "Run a bot cycle on the current game."

See the full MCP setup guide for details.

Custom HTTP Bot

Clone the templates repo and build your own bot logic:

git clone https://github.com/Metafide/spot-on.git
cd spot-on/templates/javascript

Edit the config with your API key and wallet address, then run:

node index.mjs run

The bot runs in a loop: checks for active games, generates positions, places them, and waits for the next round.

How the loop works

1. GET /spot          → Is there a game accepting positions?
2. GET /live-price    → What's the current BTC price?
3. Generate positions → Your strategy decides strike prices and amounts
4. POST /spot         → Place each position
5. Sleep 5-30s        → Wait, then repeat from step 1

What you need to handle

• Keep it running — The script stops if your terminal closes. Use screen, tmux, pm2, or deploy to a server for persistent operation.
• Rate limits — Don't poll faster than once per second. Handle 429 responses with exponential backoff.
• Game timing — Check can_place_position before placing. Games have a lock window near the end where positions are rejected.
• Error recovery — Network failures, API errors, and edge cases (cancelled games, insufficient balance) need handling in your code.

Templates

Working bot implementations are available in the templates repo:

• JavaScript — templates/javascript/
• Python — templates/python/

See the API reference for full endpoint documentation.

Which Should I Use?

Start with the MCP server if you want to get playing quickly without writing code. You can check prices, place positions, and run bot cycles through natural conversation.

Switch to a custom bot when you want full control over strategy, need to run 24/7 without an AI tool open, or want to implement advanced logic like momentum tracking, multi-account scheduling, or custom spread algorithms.

Both approaches use the same API and the same endpoints. You can use the MCP server to learn the API, then graduate to a custom bot when you're ready.