Bitget Agentic Account Connection Guide

What this document is: the first-time onboarding guide for Bitget Agentic (an online document). Hand it to an AI Agent and the Agent will walk you through the first connection — install Skill + MCP → browser OAuth → credentials generated automatically. You never create or copy an API Key by hand.

What the Agent must do: after reading this document, execute Step 0–5 in order: install the local Skill and the MCP → if this session just finished the first MCP registration, follow Step 1 and restart the session — do not call the authorization tool in this session → in the new session, call the MCP authorization tool to trigger OAuth → wait for the user to finish authorization in the browser → confirm the MCP has stored the credentials → show the completion message. Do not ask the user to create or paste a Key, and do not build the OAuth URL yourself or listen for the callback yourself.

Afterwards: once the first authorization succeeds, this document's job is done. Later Key expiry, re-authorization, trading and risk control are handled by the local bitget-agentic skill (npx @bitget-ai/bitget-agent-skill --skill agentic).

Step 0 · Install the local Skill

npx @bitget-ai/bitget-agent-skill --target all --skill agentic # by default installs to every supported client (cursor / claude / codex)

• If your client is not in the default list, specify it with --target <client>, or place the skill files into the client's directory manually as that client requires.

• --skill agentic is required. Without it, the command installs only the UTA skill (the manual-Key one).

Step 1 · Install the MCP

Prerequisite: Node 20+ (check with node -v).

Install (global):

npm i -g @bitget-ai/bitget-agent-mcp

Configuration constraints:

• Do not set BITGET_API_* environment variables (credentials are written to disk by the OAuth callback, not read from env).

• The MCP speaks the stdio protocol. The launch command to use when registering it in a client is npx -y @bitget-ai/bitget-agent-mcp (see "Client differences · MCP registration" below).

Client differences · MCP registration

The MCP must be registered in the current client before the Agent can call its tools. The Agent detects which client it is running in and performs the matching registration:

• Claude Code: claude mcp add bitget-agentic -- npx -y @bitget-ai/bitget-agent-mcp (or edit ~/.claude.json / the project's .mcp.json)

• Cursor: in Cursor Settings → MCP, add a stdio server with command npx -y @bitget-ai/bitget-agent-mcp

• Other clients: the Agent registers a stdio server using that client's own MCP registration method, with command npx -y @bitget-ai/bitget-agent-mcp

After registering, you must restart the session or reconnect MCP from the client (for example /mcp in Claude Code) before the tools appear in this session. A health check of Connected / claude mcp list showing connected only means the server can run. It does not mean this session can already call authorize_start.

After first-time registration: stop here, restart, then authorize

If this session just installed and registered the MCP, do not go to Step 2. A newly registered MCP is usually invisible to the current session; calling authorize_start will report tool not found / server not found. That is the session not being reloaded — not an authorization failure. Do not guess the cause, and do not assemble the OAuth URL yourself.

The Agent must:

1. Tell the user: Step 0–1 are done, but the authorization tool can only be called after a new session loads the MCP.

2. Give the fixed prompt below (fill in the MCP launch command you just registered; if unknown, use npx -y @bitget-ai/bitget-agent-mcp) and ask the user to paste it into the new session.

3. Tell the user how to restart for this client: Claude Code — quit this session and run claude again; Cursor — start a new Agent chat; other clients — restart the session or reconnect MCP.

4. Stop here. Do not continue OAuth in this session.

Prompt for the new session (copy this):

I have installed the bitget-agentic skill and MCP (npx -y @bitget-ai/bitget-agent-mcp). Please continue Bitget Agentic account authorization: call authorize_start to trigger OAuth, open the browser and wait while I finish sign-in / account selection / Allow / device verification on the page, then use get_auth_status to confirm authorization is complete.

Quit the current session and start again. Send the paragraph above to the new session to continue.

If a call reports "tool not found": first confirm you restarted / reconnected as above, then check whether the MCP is running — do not misdiagnose it as an authorization problem.

Step 2 · Trigger OAuth

Run 2.1 → 2.6 in order. Finish each step before starting the next.

2.1 Gate: is authorize_start in this session's tool list?

• No → do not call it, do not assemble a URL, do not continue. Run the four actions from "After first-time registration" in Step 1 (explain the state → give the fixed prompt → say how to restart → stop working in this session).

• Yes → go to 2.2.

2.2 Call authorize_start

The authorization link must come from this tool. The LLM must not assemble the URL itself or start a local server to listen for the callback.

Before the call, set authorizeBaseUrl (the domain must match the URL in the user's current prompt):

1. Look in the user's current message for a URL (for example: "Please read [https://www.bitget.cloud/...] and help me complete...").

2. If there is a URL → take its scheme + host (for example https://www.bitget.cloud) and pass it to authorize_start as authorizeBaseUrl. Do not guess the region. Do not substitute a different domain.

3. If there is no URL → omit authorizeBaseUrl and use the SDK default domain.

If the call fails → go to the "First-time OAuth failure" section and handle it by error code. Do not continue to 2.3.

2.3 Read two fields from the response

Field	Use
data.authorizeUrl	The authorization link to open. Use it exactly as returned; never build or modify it.
sessionId	Pass to authorize_wait in 2.5.

2.4 Open the browser

If the browser does not open on its own, the Agent runs the command itself — do not wait for the user to copy and paste:

• macOS: open "<authorizeUrl>"

• Linux: xdg-open "<authorizeUrl>"

• Windows: start "" "<authorizeUrl>"

Only if the command fails (no GUI / no browser / command missing) should you send the link text to the user to open themselves.

Send this to the user at the same time:

I'm about to open the browser to authorize your Agentic account: sign in → choose Create new or Use existing → Allow → device verification in the Bitget App → if you pick Use existing you'll need to enter a Key label. You do not need to copy an API Key.

2.5 Wait for the authorization result

After the user completes authorization in the browser, the MCP/SDK receives the credentials through the callback and saves them locally (see Step 5). The Agent confirms this one of two ways:

 

• Call authorize_wait with the sessionId from 2.3 and wait for it to return; or

• Call get_auth_status and confirm the state is authorized.

2.6 Decide

• Authorized → go to Step 5.

• Not authorized / timed out / error → go to the "First-time OAuth failure" section. Do not treat a browser page that looks finished as success.

Step 3–4 · In the browser (user acts, Agent waits)

• Step 3: sign in; if KYC is incomplete → finish it on the site, then do OAuth (Case L)

• Step 4: Create new or Use existing → device verification in the App

  • Create new: creates a new Agentic account

  • Use existing: selects an existing Agentic account, and requires a Key label

  • No Playbook involved · re-authorizing = a new Key, and the old Key is kept (re-authorizing updates the credentials on this machine; on the Web the old Key is kept by default)

  • Account selection happens in the OAuth front end; the Agent only triggers authorization and waits for the result

Step 5 · Success

The MCP writes the three credentials to disk locally, and the browser lands on the assets page. get_auth_status returns authorized.

• The three credentials = API Key, Secret Key, Passphrase. They are received on the callback side by the MCP/SDK and saved locally; the Web does not store them; the user does not copy or paste anything.

• How success is judged: it counts as done only when the MCP confirms the credentials are saved and the authorization state is successful. A finished browser page is not proof of success.

Message to the user:

First-time authorization is complete. If the Key stops working later, or you say "re-authorize", I'll reopen OAuth. To revoke this Agent's trading permission, delete the API Key for that Agentic account on the Bitget website; deleting the Key does not automatically close positions or cancel open orders. Next, please manually transfer a small amount you're comfortable risking from your Bitget main account to the Agentic account. Once it arrives, say "check the Agentic account balance" first, then try trading. The transfer and any main-account operations are yours to do; I will not touch your main account and can only operate the authorized Agentic account. Which assets are actually tradable depends on the account's currently supported scope.

Do not ask the user to paste a Key. From here on, the local Skill takes over. If the bitget-agentic skill is not loaded in this session (the skill list is scanned at session start, so a skill installed during this session may be unavailable), tell the user to start a new conversation and continue there — the new session loads that skill automatically, which is what gives the Agent its runtime rules.

 

First-time OAuth failure (this Guide only)

Attribute causes by error code only: when the authorization tool returns a specific error code, handle it by that code. When there is no specific error code, always fall back — do not guess the cause; just run the authorization flow again.

Error code → action:

Error code	Action	Message
Quota error code (K, quota full)	Use existing	"Please choose Use existing instead."
KYC error code (L, KYC incomplete)	Finish KYC, then OAuth	"Please complete KYC first."
MCP_CONNECTION_ERROR (M, MCP not running)	Troubleshoot, then OAuth	"Please check Node 20+ and the MCP configuration, and run npx @bitget-ai/bitget-agent-mcp in a terminal."
Tool not found / method not found (M2, MCP not installed or not registered)	Guide the install + registration, then retry	"MCP tool not found: please run npm i -g @bitget-ai/bitget-agent-mcp, register it, and retry."

Fallback (no specific error code): for a generic failure, a timeout, a callback never received, or an uncertain browser state, the Agent cannot know the real cause (cancelled, didn't finish, closed the page, etc.). Do not guess. Say "authorization not completed" and run the authorization flow again:

"Authorization wasn't completed. Please confirm you finished the authorization steps in the browser — want me to start it again?"

Forbidden: having the user create and paste a Key manually · promising one-click re-issue · trading before OAuth is complete · guessing at a cause when the failure reason can't be confirmed

Capabilities without authorization: while unauthorized, public capabilities that need no Key (such as market data) still work; trading capabilities do not.