Cove Agent MCP

• A Global token reaches every real wallet in every profile you own, including wallets and profiles you add later.
• A Profile token is pinned to one profile and only the wallets you pick in it.

​

Contents

• What your agent can do
• Quick start
• Connection details
• Requesting access
• Global vs Profile tokens
• Your tokens
• Wallet permissions
• Connecting AI apps with OAuth
• Working across your wallets
• Rate limits
• Spending limits
• Staying safe
• Confirming high-impact trades
• Recovering from an uncertain result
• Trade timing across wallets
• Gas-surplus offers
• Notifications & webhooks
• Tool reference
• Errors & availability
• Need help?

​

What your agent can do

• See everything — USDC balance (including funds still bridging), open positions with live PnL, order status, authoritative fills, and full trading history.
• Research tokens — search, pull detailed info, and run a security report (rug checks: audit verdict, mint/freeze authority, holder concentration, liquidity locks).
• Trade — market buys and sells across up to 25 wallets in one call, with a Telegram notification to you for every wallet.
• Automate — limit buys, stop-losses, take-profits, trailing stops, and DCA ladders.
• Manage — read and update trade/position settings, check earnings, request payouts, export trade history.
• Organise (Global token) — create, rename, archive, and restore profiles; create and rename wallets; pick your primary (payout) wallet.
• Move funds (needs Money-out) — withdraw to an external wallet, send USDC to another Cove user, move tokens between your own wallets, bring USDC home from other chains, buy aged wallets from the marketplace, and privately fund your own wallets.

​

Quick start

​

Connection details

{
  "mcpServers": {
    "cove-trading": {
      "url": "https://cove.trade/api/mcp",
      "headers": { "Authorization": "Bearer <your-read-write-token>" }
    },
    "cove-read": {
      "url": "https://cove.trade/api/mcp",
      "headers": { "Authorization": "Bearer <your-read-token>" }
    }
  }
}

​

Requesting access

• You create and manage all tokens yourself in /agent — Global or Profile, any profile.
• You choose which wallets a Profile token reaches, and whether each may move money.
• You set your own spending limits.

​

Global vs Profile tokens

​

Your tokens

​

Managing tokens in /agent

• Rotate any time you suspect a token is exposed. Your rate limit and spending history follow you, not the token, so rotating never resets them.
• New wallets aren’t added to a Profile token automatically — open Manage Wallets and select them. (A Global token picks them up by itself.)
• A wallet covered by a Profile token can’t be moved to another profile until you revoke or re-scope the token.
• Requirements: agent access enabled on your account, and a Cove account linked to Telegram (that’s where agent notifications go).

​

Managing tokens programmatically

​

Wallet permissions

​

Connecting AI apps with OAuth

​

Set up an OAuth connection

Step-by-step visual walkthrough: Connecting Cove MCP to an AI agent

1

1. Enable AI App Connections in Telegram and copy your MCP URL

Open Cove in Telegram and type /agent. Select the Global agent token tab. Toggle Connect AI apps: ON. Tap Copy URL to copy your global MCP server endpoint.

2

2. Open Plugins or Connectors in your AI application

Launch your AI client (such as ChatGPT, SuperGrok, Claude, or OpenWebUI). Go to the settings or plugin section and select Connectors. Click New Connector in the top right corner.

3

3. Add a custom connector

In the connector options modal, choose + Custom: Add your own custom connector.

4

4. Name the connector and paste your MCP server URL

Enter a recognizable name (for example, Cove Trading). Paste your copied MCP URL (https://cove.trade/api/mcp) into the Server URL input box, then click Add Connector.

5

5. Initiate OAuth authorization

Your AI client launches a Cove OAuth authorization pop-up window titled Approve this connection in Telegram. Note the 6-character verification code (for example, ASHM-U) displayed on screen.

6

6. Click Open Cove in Telegram

Click Open Cove in Telegram. The pop-up window switches state to Waiting for your approval in Telegram.

7

7. Verify the code and approve in Telegram

In Telegram, Cove displays a Connect an AI app? approval request. Confirm that the self-reported app name and 6-character verification code match your browser window, then tap Connect.

8

8. Receive Telegram confirmation

Telegram displays an approval confirmation: AI app approved. Return to your browser to finish connecting.

9

9. Confirm active connection status in your AI app

Return to your AI client window. Under the Connected connectors list, your Cove connector now displays a ✓ Added badge.

10

10. Execute trade commands using plain text prompts

Prompt your AI agent with trading instructions in natural language (for example: “using my main wallet, buy $5 worth of [token address]”). The agent calls Cove MCP trading tools, executes the market order, and returns full transaction details.

11

11. Review real-time Telegram execution alerts

Cove sends an instant notification to your Telegram chat (🤖 Agent Buy / Buy Executed), updating your position card, PnL, and active order guardrails.

12

12. Manage and exit positions through conversation

To sell holdings or adjust positions, chat naturally with your agent (for example: “Ok, sell the balance”). The agent triggers the sell order via MCP and provides a complete net summary.

• Connect AI apps → OFF disconnects every connected app. Turning it back on requires fresh approvals.
• Rotating or revoking the Global pair also disconnects every app, and turns Connect AI apps off again.
• There’s no per-app disconnect yet — turn the toggle off and reconnect the apps you want.

​

Working across your wallets

• get_positions, get_trading_history, and export_trades — omit the target to cover all in-scope wallets, or narrow with accountIds / accountId.
  • get_positions returns a flat list when you name exactly one wallet, and { accounts: [{ accountId, positions }] } otherwise.
  • get_trading_history returns up to limit (1–100, default 20) orders per wallet, merged newest-first, optionally filtered by status.
• get_balance is per-wallet: pass an accountId (it can be omitted only when the token reaches exactly one wallet).

{
  "tokenSymbol": "BONK",
  "status": "partial",
  "submitted": [{ "accountId": "01J…A", "status": "submitted", "orderId": "01J…" }],
  "rejected":  [{ "accountId": "01J…B", "status": "rejected", "code": "insufficient_balance", "reason": "…" }]
}

​

Rate limits

• The window is a fixed 60 seconds, not a sliding one.
• Over the limit, you get HTTP 429 with Retry-After and RateLimit-* headers — back off until then.
• One JSON-RPC request per HTTP call; batches are rejected.

​

Need a higher limit?

• How you intend to use the MCP — the kind of agent, the workload, roughly how many calls per minute you expect and when (steady, bursty, scheduled runs, etc.).
• How much of an increase you need — give us a target requests-per-minute.

​

Spending limits

• A 5-wallet buy at $500 each is $2,500 of spend — it passes a $500 Per-Trade limit, but not a $1,000 Per-Batch limit.
• Hourly and daily totals count spending by all your agent tokens; each call is checked against the calling token’s limits.
• Still-open limit buys and pending workflows keep counting even after their window record ages out.
• If Cove can’t verify your open exposure, the trade is refused rather than risked.

​

Staying safe

• No accidental double-trades. Every trade, limit order, and money-out takes an idempotencyKey you generate — 8–64 characters of letters, digits, _, or - (a UUID works). Retry with the same key and same parameters within 10 minutes and you get the original result back — not a second trade. A market order’s key is also remembered permanently per wallet, so it can’t be reused for a different trade later. Bridge, marketplace, and private-disperse tools take a key of 8–128 characters that is stored permanently and tied to the token that used it.
• One trade per token at a time. Two buys (or two sells) of the same token within ~2 seconds are held back — including one from the mini app — so a double-tap can’t double-spend.
• High-impact trades pause for confirmation. A trade with unusually high price impact comes back asking you to confirm, and nothing is spent until you do. The confirmation is tied to the exact quote shown. See Confirming high-impact trades.
• Trades stay sellable. A buy that would leave a position too small to ever sell is refused up front — the minimum is $2.50 on Solana and $0.50 on other chains (the $1 minimum order also applies).
• Spending limits. Set them yourself in /agent — see Spending limits.
• Read tokens can’t spend. A read-only token can’t trade or move money at all.
• Money-out is opt-in on Profile tokens, per wallet.
• No keys ever leave Cove. No tool exports private keys or creates new credentials.
• You’re always told. Agent trades, holds, refusals, and money movements send a Telegram message to your linked account — see Notifications.

​

Confirming high-impact trades

{
  "confirmHighImpact": "high",
  "confirmImpactPromptIds": { "<accountId>": "<promptId>" }
}

• Use the code exactly as returned. If wallets came back with different classes, confirm them in separate calls.
• Name only the gated wallet(s) in accountIds, and use a fresh idempotencyKey — unless you’re re-sending the entire original call and none of it went through, in which case the original key is fine.
• A prompt lasts 10 minutes and is single-use.
• If the new quote is more than 5% worse than the terms you confirmed, or the impact class gets worse, the trade asks again instead of executing (quoteChanged: true).

​

Recovering from an uncertain result

1. Call it after a lost or ambiguous response — including any “Buy failed” / “Sell failed” error without a code.
2. Poll found results until every order is terminal and every success shows fillStatus: "authoritative", with a fill (amount, USD, price, fees, time).
3. Treat not_found and unavailable as uncertain — stop and tell the user. A not_found does not mean it’s safe to trade again.
4. Market orders can’t be cancelled once submitted.

​

Trade timing across wallets

• If you leave it out: buys use each wallet’s profile Transaction delay setting; sells go out together; a single-wallet call never waits.
• Primary wallet first: if the profile has Primary wallet first on and you name the primary wallet, it goes first and the rest wait at least 250 ms.
• Delays control submission order only — fills land in whatever order the chain settles them. All order ids come back immediately; later wallets show pending until their turn.
• batch_order protection waits for the fill. The stop-loss and take-profit are created straight away but stay dormant until that wallet’s buy actually fills. If the buy fails or its outcome is unknown, the protection waits (until recovery, cancellation, or expiry) rather than firing.
• An agent buy that fails because the wallet couldn’t afford it at execution time is not automatically retried at a smaller size — reconcile, then submit a new call.

​

Gas-surplus offers

• For a failed market order, get_trade_surplus_offer({ orderId }) returns the live offer: offerId, surplusUsd, expiresAt, and the exact continuation call.
• To accept, call that buy_token / sell_token continuation exactly as given, with surplusOfferId and maxSurplusUsd (up to $1,000), for one wallet, using the supplied idempotencyKey. You’re only ever charged the offered amount.
• Offers expire within 10 minutes and are tied to your token. An accepted sell surcharge counts toward your spending limits. Paper wallets and Solana sells don’t get offers.
• Accepting doesn’t change your saved gas surplus budget setting.

​

Notifications & webhooks

​

Telegram

​

Webhooks

• Headers: X-Cove-Event (the event) and X-Cove-Signature = HMAC-SHA256(webhookSecret, rawBody) in hex — verify it before trusting the payload.
• Payload: event, orderId, accountId, status, tokenSymbol, tokenAddress, chainId, side, amountUsd, tokenAmount, priceUsd, txHashes, timestamp. A fan-out sends one delivery per wallet.
• Delivery is best-effort: a 5-second timeout and no retries. Limit-order and DCA fills don’t send webhooks. Treat reconcile_market_order / get_order_status as the source of truth.
• Your webhook and secret carry over when you rotate tokens.

​

Tool reference

• Needs: read = any token; RW = read-write token with trade on the target; RW + money-out = read-write with Money-out on the source wallet; Global RW = a Global read-write token.
• Wallets: all = defaults to every in-scope wallet (narrow with accountIds/accountId); fan-out = accountIds, one independent order per wallet; one = a single accountId; — = not wallet-specific.

​

Discover

​

See your account

​

Research tokens

​

Trade

​

Automate (limit orders)

​

Settings & earnings

• Global tokens must pass profileId to read or write settings; Profile tokens use their own profile.
• A Profile token can only write profile-wide settings if it covers every wallet in that profile.
• Change at most one of slippageBps, clampToMaxBuy, or liquidityProtectionEnabled per call. Changing any of them turns degen mode off in the same write, so don’t combine them with degenMode: true.
• language needs a Global token. tradingSelectedAccountIds is read-only.
• If an update fails part-way, trust the observed field in the response — it’s a fresh read of what’s actually saved.

​

Profiles & wallets

​

Move funds

​

Bridge

​

Wallet marketplace

​

Private disperse

​

Errors & availability

• Cove can pause the MCP globally for maintenance or emergencies; you’ll get a clear “temporarily paused” / “disabled” response if so.
• A feature that’s switched off on the deployment still appears in tools/list and refuses when called — check get_capabilities to see what’s enabled.
• Over the rate limit you’ll get HTTP 429 with Retry-After.

​

Need help?