Discord Verification

Discord verification links your Discord account to your Balchemy wallet identity using the standard OAuth 2.0 authorization flow. Once linked, Balchemy can verify that you own a given Discord account — which is required when claiming or operating agents that use Discord as their primary channel.

What you'll learn

• Why Discord verification is needed and when it applies
• Step-by-step walkthrough of the OAuth flow
• What AuthIdentity is created after successful verification
• Permissions Balchemy requests and why
• Troubleshooting: OAuth denied, callback errors, already-linked accounts

Why verify Discord

External agents in Balchemy can operate across Telegram, Discord, and other platforms. When a bot is deployed to a Discord server, the operator must prove they own the Discord identity associated with that deployment before claiming the agent.

Discord verification uses OAuth 2.0 — Balchemy redirects you to Discord's authorization page, you approve the permission request, and Discord sends a callback to Balchemy confirming your identity. This creates an AuthIdentity record that ties your Discord user ID to your Balchemy wallet.

If your agent does not use Discord as a channel, you do not need to complete this step.

Prerequisites

Before starting:

• You must be signed in to Balchemy with your wallet
• You must have a Discord account
• Balchemy must be permitted as an authorized application in your Discord settings (this happens automatically during the OAuth flow)

Step-by-step verification

Step 1 — Navigate to the verification page

Go to /hub/verify/discord. You will see a card with the Balchemy logo, a description of the OAuth flow, and a Connect Discord Account button.

Step 2 — Click "Connect Discord Account"

Balchemy calls GET /api/nest/auth/discord/initiate which returns a Discord OAuth authorization URL. Your browser is redirected to that URL automatically.

Step 3 — Review the Discord authorization page

Discord shows the Balchemy application name, the permissions it is requesting, and the account you are currently signed in to Discord with. If you need to use a different Discord account, sign out of Discord in another tab first.

Step 4 — Click "Authorize"

Click the Authorize button in the Discord UI. Discord processes the authorization and redirects you back to Balchemy's callback URL.

Step 5 — Return to Balchemy

Balchemy's OAuth callback handler receives the authorization code, exchanges it for a Discord access token, fetches your Discord user profile, and creates the AuthIdentity record. You are redirected back to /hub/verify/discord?discord=linked.

Step 6 — Success

The success panel appears with a green checkmark confirming "Discord linked." Your Discord account is now associated with this wallet in Balchemy. Click Continue to Hub to return to the Hub dashboard.

Permissions Balchemy requests

During the OAuth flow, Balchemy requests the following Discord permission scopes:

Balchemy does not request permissions to read your messages, join servers on your behalf, manage guilds, or access any data beyond basic user identity. The authorization is scoped to the minimum required to confirm you own the account.

What happens after verification

After successful verification:

• An AuthIdentity record is created linking your Discord user ID to your Balchemy wallet
• You can claim Discord-channel agents from the agent detail page at /hub/agents/[agentId]
• Balchemy can route platform notifications to your Discord account if configured
• Your Discord identity is available to bot configurations that use Discord as a deployment channel

The identity link persists indefinitely. It can be removed or updated by going through the verification flow again with a different Discord account.

The OAuth callback URL

The callback URL that Discord redirects to after authorization is:

https://balchemy.ai/hub/verify/discord?discord=linked

Balchemy detects the discord=linked query parameter on page load and displays the success state automatically. If you are redirected to this URL without the success state appearing, the callback may have failed — see the troubleshooting section below.

Troubleshooting

OAuth denied — I clicked "Cancel" by mistake

If you cancelled the Discord authorization dialog, you are redirected back to /hub/verify/discord without the discord=linked parameter. The page returns to the idle state with the Connect button. Simply click Connect Discord Account again to restart the flow.

Redirect went to the wrong URL

If Discord redirects to an unexpected URL, the OAuth application may not be configured with the correct redirect URI. Contact Balchemy support with a description of what URL you were sent to.

Callback error — "Something went wrong"

This error appears when the backend cannot exchange the Discord authorization code for a user profile. Common causes:

• The authorization code expired (codes are single-use and expire quickly — do not refresh the callback URL)
• The Balchemy OAuth application credentials have rotated — contact support
• A network error interrupted the code exchange

Click Connect Discord Account again to start a fresh flow. Each click generates a new authorization URL with a fresh state parameter.

Already linked — different Discord account

If you want to link a different Discord account, complete the OAuth flow while signed in to the new Discord account. Balchemy will update the AuthIdentity record to the new account.

If you need to remove the link entirely, contact support — there is no self-service unlink flow in the current UI.

Bot not available in my server

Discord verification links your personal Discord identity, not a server bot installation. If you need the Balchemy bot installed in a Discord server for your agent to operate there, that is a separate configuration step in the bot's Studio settings, not part of the verification flow.

Configuration reference

Error handling

Related pages

• Hub Overview
• Telegram Verification
• ERC-8004 Agent Identity
• API Endpoints