GridBot AI MCP Connector documentation
Last updated: 2026-10-02
What it is
The GridBot AI connector lets an AI assistant you trust read your grid-bot state and take a fixed set of actions for you. It is available to paid subscribers.
Connector URL. Enter it exactly as written:
https://gridbotai.com/mcpNo trailing slash. The address is compared byte for byte during authorization, and a trailing slash gives you a connector that signs in and then refuses every call.
A connector you added earlier with the old address, https://spotgrid.bagbaazar.com/mcp, no longer works. Remove it in your AI app and add it again with the URL above.
Prerequisites
- A GridBot AI account on a paid plan.
- A verified email address.
- At least one grid runtime.
mainis the primary bot; Multi Grid runtimes have hex ids you can list withspotgrid.list_runtimes.
Connecting
GridBot AI is not in Anthropic's or OpenAI's connector directories. The listing material is written, but nothing has been submitted or approved yet, so you add it manually as a custom connector. That is the supported way to use it today.
The same instructions are in the dashboard, on the AI connector page, and in the guide at /#/docs.
Claude (web, desktop, mobile)
Customize → Connectors → Add custom connector → paste the URL above → Add. Leave the OAuth client fields empty; the server registers the client itself.
A pre-filled link you can put behind a "Connect to Claude" button:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=GridBot%20AI&connectorUrl=https%3A%2F%2Fgridbotai.com%2FmcpClaude Code
claude mcp add --transport http gridbot https://gridbotai.com/mcpThen run /mcp in the REPL to complete sign-in. Claude Code uses a loopback redirect on a random port, which the authorization server accepts.
ChatGPT (developer mode)
Settings → Connectors (on some plans, Apps and connectors) → the advanced or developer section → enable developer mode, then create a connector pointing at the URL above and choose OAuth as the authentication. On a work account an administrator may have to allow developer mode first.
What happens when you connect
- You sign in to GridBot AI in your browser.
- You see which AI app is asking, and you choose:
- which grids it may use. Your grids are listed by name. "Grids I create later" is a separate choice, off unless you tick it;
- what it may do on them, the same for every grid or set grid by grid (see [Permissions](#permissions));
- for how long: 1 hour, 24 hours, 7 days, 30 days, a custom length, or no expiry.
- If you turned on Extra safety, GridBot AI also emails you a six-digit code to enter on that page. GridBot AI will never ask you to type a code into a chat window.
- You hold Allow. The app gets a token that lasts 15 minutes at a time and is refreshed automatically, for as long as at least one of its grids still has time left.
Permissions
Access is set per grid, from eight permissions. A tool works only on a grid where the connection holds the permission it needs. You can change or remove any of them at any time on the AI connector page, and the change applies to the app's very next call, not when its token next refreshes.
| Permission | What it allows |
|---|---|
| Balances and bot status | USDT and coin balances, running or stopped, open profit |
| Grid orders | open buy and sell orders |
| Trade history | filled trades and realised profit |
| Grid settings | price range, spacing, order size, trading style |
| Grid control | start, stop, kill switch, cancel buy orders, recover |
| Trading style | switch the grid to another trading style |
| Group sell | preview and sell coins the grid holds |
| Delete grid | remove the grid and its settings |
list_runtimes, get_usage, list_audit and get_assurance_status are about the connection or the account rather than one grid. They work while any of the connection's grids still has time left.
When a call is refused, the app is told why: permission_denied names the permission that is missing on that grid, and access_ended says the time you set has run out. A grid the connection was not given answers exactly like a grid that does not exist.
The tools
Read
| Tool | What it does | Needs |
|---|---|---|
spotgrid.list_runtimes | the grids this connection may use, with its permissions on each | any grid |
spotgrid.get_status | running/stopped, paper/live, kill-switch state, open order counts | Balances and bot status |
spotgrid.get_config | symbol, geometry, risk profile, allocation. Never credentials | Grid settings |
spotgrid.list_orders | open BUY and SELL orders | Grid orders |
spotgrid.list_history | completed fills and realised profit, paginated | Trade history |
spotgrid.get_usage | plan, usage against the cap, what is currently permitted | any grid |
spotgrid.list_audit | your own recent MCP activity | any grid |
spotgrid.get_assurance_status | this connection's permissions, and any requests waiting for you | any grid |
Reading the numbers these return
History comes back one page at a time. has_more says whether fills remain behind the page, and next_cursor is present whenever they do; pass it back to continue. A summary built from one page covers that page only.
A cursor marks the exact fill a page ended on, not a row count, so trades booked while you are paging cannot shift the window. You will not see the same fill twice or skip one, even when several fills share a millisecond. Fills that arrive after you start show up at the head of a fresh listing, not in the middle of the one you are walking. A cursor from an older release is refused with argument_invalid; start the listing again.
realized_pnl is gross: the price achieved minus buy_price, the basis actually paid. fee_usdt is the fee recorded against that one fill and realized_pnl_net is the gross less that fee. The other leg of a round trip carries its own fee on its own row. fees_estimated: true means the fee was modelled rather than charged by an exchange, which is always the case in PAPER mode (where mode: "paper" says so) and in LIVE whenever the venue did not report one.
A reported order quantity is the size actually submitted, which can differ from the template. The venue's step size, the dust retained on a SELL, and a partially filled order still reporting the size it was placed at can each move a rung's size. Every order carries configured_quantity, the template for its side, and the response carries sizing with the venue's step, minimum quantity and minimum notional, so you can work out where a difference came from.
The identifiers are opaque aliases. order_id, trade_id and rung_id stay stable, so the same order is the same alias on every call; de-duplicating rows and pairing a SELL with its BUY (equal rung_id) both work. They are not the identifiers GridBot AI or the exchange uses internally and cannot be turned back into them.
A missing field means the value is unknown. created_ms is absent from an order whose creation time was never recorded; it is not reported as zero.
The fee you are actually charged is not always the one you configured. With fee_mode: auto, buy_fee_pct and sell_fee_pct read 0 while real fees are still being taken, so get_config also returns effective_buy_fee_pct / effective_sell_fee_pct and a fee_source: manual (the configured percentage is charged), manual_fixed (a flat USDT amount per fill), learned (measured from real exchange fills), paper_default (the simulator's own rate, before any real fee has been observed) or unobserved (live, nothing measured yet, so the rate is unknown).
Under manual_fixed the charge is effective_buy_fee_usdt / effective_sell_fee_usdt, which is exact. A flat fee has no percentage until there is a price to express it against, so effective_*_fee_pct is omitted in that case rather than reported as 0.0.
Totals are per page. page_totals on a history response sums the rows in that page (gross, fees and net) and includes the BUY rows, whose only content is a fee. It is not a lifetime total; has_more says whether anything is behind it.
expected_pnl is what the rung was designed to make: the grid spacing at that fill times the quantity, on SELL rows only. In LIVE the gap between it and realized_pnl is slippage, a partial fill, or a rung that moved. In PAPER the two coincide, because a simulated limit order fills at its limit price.
Billable volume counts LIVE trading only. get_usage reports 0.00 used for an account that trades only on paper or testnet, and that is correct: paper trades simulated money and is never billed.
list_runtimes shows only what you shared. Grids the connection was not given, or whose time has run out, are absent from the listing exactly as a grid that does not exist would be: same rows, same fields, nothing standing in for what was withheld. Each row it does show carries permissions and access_expires_at. The primary marker names your included bot, so when the primary is not among the grids you shared, the marker is absent altogether, and a client can read that as "the primary is outside my scope". The marker cannot be dropped without misnaming which grid is the included bot, and it says nothing about how many grids you withheld or which ones.
conn_id in list_audit names one connected session. It stays the same for as long as a client remains connected, across token refreshes, and differs between two sessions. client_id cannot show that, because every connection from one AI platform reports the same client.
Repeated refusals are collapsed into a summary. Rate limits, the concurrency guard, an approval request that could not be opened and the plan check all write an audit row, but a client that loops on one of them writes at most one row per minute per connection, and that row carries suppressed_in_previous_window saying how many it stands for. The class, the caller and the minute are always recorded; the exact size of a burst is not.
Protective (reduces exposure, never waits)
spotgrid.stop_runtime · spotgrid.cancel_open_buys · spotgrid.kill_switch · spotgrid.recover · spotgrid.group_sell_preview
These run at once. A stop button that asks first is not one.
Cancelling BUYs never touches the SELL orders that exit a position you already hold. Stop, cancel open buys and delete also cancel a part-filled BUY; the coins it already bought stay in your wallet, with no SELL placed for them. A preview places no orders; it works out what a sale would realise and returns an identifier valid for 120 seconds.
Exposure-increasing (puts capital at risk)
spotgrid.start_paper · spotgrid.start_live · spotgrid.update_risk_profile
PAPER simulates and risks nothing. LIVE places real orders with real funds.
Destructive (irreversible)
spotgrid.group_sell_execute · spotgrid.delete_grid
Trading styles
spotgrid.update_risk_profile switches a runtime between five named styles. They commit the same 90% share of the wallet and differ only in how far apart the rungs sit, tightest to widest. The grid size, quantity and lowest buy price for a given wallet and BTC price are derived per runtime — read them from spotgrid.get_config or the dashboard preview, never assumed from this page.
- Greedy (tightest) — earns from the smallest moves and trades most often; spends USDT fastest, and can stop buying if it runs out in a sustained drop.
- Aggressive — frequent round trips on close spacing; still drains USDT quickly in a falling market.
- Balanced — middle spacing, a steady rhythm; earns less than the tight styles in a quiet, narrow range.
- Safe — wide spacing reaches deeper on the same balance and lasts longer in a drop; fewer, larger trips, so it earns less when the market barely moves.
- Boomer (widest) — deepest reach and slowest USDT burn, best for large infrequent swings; rarely trades in calm markets.
Selling always stays active and your exchange wallet keeps every asset you buy — only buying can pause, and only when USDT runs out. It resumes when price returns to range or you top up USDT.
For a sense of scale — illustrative only, computed at BTC = 62,500 USDT with a 50,000-USDT wallet (each style commits 90%). "Max Lowest Buy" is the deepest rung's price and how far below the reference it sits. A live runtime's numbers come from spotgrid.get_config / the dashboard preview, never this table:
| Style | Grid Size | Quantity | Max Lowest Buy (price / %) |
|---|---|---|---|
| Greedy | $58 | 0.01252 BTC | $61,828 / 1.1% |
| Aggressive | $108 | 0.01878 BTC | $61,236 / 2.0% |
| Balanced | $216 | 0.02817 BTC | $60,048 / 3.9% |
| Safe | $432 | 0.04225 BTC | $57,456 / 8.1% |
| Boomer | $864 | 0.06338 BTC | $55,296 / 11.5% |
Approvals
On a LIVE grid, four actions wait for you before they run:
| Action | Waits on LIVE | Waits on PAPER | After you approve |
|---|---|---|---|
Start in LIVE (start_live) | yes | yes, because it makes the grid live | runs the next time the app asks |
Change trading style (update_risk_profile) | yes | no | runs the next time the app asks |
Group sell (group_sell_execute) | yes | no | 60 seconds in which you can stop it |
Delete grid (delete_grid) | yes | no | 60 seconds in which you can stop it |
Everything else runs at once, within the permissions you gave.
How it works:
- The app makes the call. Instead of running it, GridBot AI answers
approval_requiredwith a link and a one-line summary of the action. - You open the link (or the AI connector page) while signed in to GridBot AI, read exactly what will happen, and hold Approve, or press Decline. Nobody else can answer it: the link only works in your own signed-in browser, and the app that asked cannot approve its own request.
- The app makes the same call again. It runs once. A different grid, tool or setting is a different action and is asked about separately.
A request you do not answer ends after 10 minutes and nothing happens. An approved action has to be used within 10 minutes of becoming runnable, or it ends too. It becomes runnable at once, except a group sell or a delete, which waits 60 seconds first. For those two, Stop it works from the moment you approve until the action actually runs, not only during the 60 seconds. If you decline or stop a request, the app is told the next time it asks, and the call after that is a new request.
If you take away the permission an open request needs, the request ends, and giving the permission back does not revive it: the app's next call asks you again. Connecting the app again ends its open requests the same way.
The approve page cannot run anything by itself; only the app's next call does. That is why the page says "runs the next time the app asks".
If a grid switches between paper and live after the app's call was checked, nothing runs and the app is told mode_changed. Its next call follows the rules for the mode the grid is in now, so a grid that went live asks for approval again. A delete is the one exception to "nothing runs": the grid may already have been stopped and its BUY orders cancelled, but it is not deleted. A group-sell preview is not used up by such a call.
Extra safety
Extra safety is off by default. Turn it on from the AI connector page and GridBot AI also asks for a six-digit code it emails you before you can:
- connect a new AI app,
- approve a waiting request,
- give a connection more access (a new permission, a later end, or no end),
- turn Extra safety off again.
Taking access away never needs a code. A code lasts 10 minutes, can be used once, and five wrong tries end it.
An emailed code proves you control the mailbox and that the act was recent. It is not a second authentication factor, and GridBot AI does not claim it is one.
GridBot AI never reads your mail. It only sends it; there is no mailbox integration in the service at all. No tool accepts a code, an approval or a "confirm" flag, so an assistant that can read your mailbox still cannot approve anything for you: approving takes your own signed-in browser.
Idempotency
Every action tool takes an idempotency_key. Retrying with the same key returns the original result instead of acting twice; the client generates it. Keys are remembered for 24 hours.
Limits
| Limit | Value |
|---|---|
| Read calls | 120 per minute |
| Protective calls | 30 per minute |
| Exposure-increasing calls | 10 per minute |
| Destructive actions | 3 runs per hour, one at a time; approval requests, waits and replays not counted |
| New approval requests | 20 per hour per account |
| Result size | capped, with an explicit marker when truncated |
Billing behaviour
If your subscription lapses, reading and protective actions keep working, provided the connection was set up while it was paid and has not been revoked. Starting or changing trading, and destructive actions, stop immediately. Releasing a kill switch on a lapsed plan is limited to three times a day. A failed invoice never leaves you unable to stop a bot.
The action log
Everything a connected app does, everything you approve, decline or stop, and every change you make to a connection is recorded in the action log on the AI connector page. GridBot AI does not email you a receipt for each one; the log is the record.
Changing and revoking access
Dashboard → AI connector. For each connection you can change its grids, permissions and end dates, disconnect it, or remove an ended one from the list.
The panic control does these things, in this order: it cuts off every AI connection in the connector, so nothing an AI app sends from that moment can act; it tells the trading backend to refuse anything but protective actions from those connections, so a request already on its way cannot act there either; it arms the kill switch on every one of your grids, cancels the resting BUY orders on each of them; and then it records the revocation in the trading backend as well. Your SELL orders are left alone. They are the exit for inventory you already hold, and cancelling them would add to your exposure in the middle of an emergency stop.
It reports what happened per grid: if a grid could not be reached, you are told which one, and the connections are revoked anyway. Each step runs even if an earlier one failed: a connection that could not be cut in the connector does not stop your grids being protected. Your grids are protected even when no AI app is connected any more, or none of them can reach the trading backend: panic then uses your own signed-in session for it. If your grids could not be listed at all, the answer says that no grid could be checked. Revocation is immediate and reaches the trading backend as well as the connector; it does not wait for a token to expire. Requests that were waiting for you end with it. You then get one email saying whether the stop finished, and if it did not, what did not: grids not protected or not checked, or connections not revoked.
Getting help
https://gridbotai.com/support · support@gridbotai.com Security: security@gridbotai.com · https://gridbotai.com/security