Skip to main content

Connect an agent

To let an agent pay for services, it needs access to your wallet. There are three ways, depending on the agent. All of them are scoped: an agent can read balances and pay for services and approved payees, but it can never approve a new recipient or raise your spending limit (those need a browser login).

1. MCP connector with OAuth (Claude.ai, ChatGPT)​

Chat clients that support MCP connectors use OAuth 2.1, so there are no codes to copy.

  1. In the client, add a custom connector pointing at the XDC AI MCP server: https://api.xdcai.tech/mcp.
  2. The client discovers our OAuth server automatically (at https://xdcai.tech/.well-known/oauth-authorization-server), registers itself, and opens a browser tab.
  3. Log in with your email and approve the request (scope: view your address and balances, and pay for services).
  4. The client receives a token and can now pay on your behalf, within your spend caps.

No client secret is involved; the flow uses PKCE. You can revoke access by removing the connector in the client.

Shell-based agents use the xdcai CLI. Logging in opens a link you approve in the browser - the CLI then holds a session; you never paste a code.

npx xdcai@latest login
# Opens (or prints) a link like https://xdcai.tech/connect?code=...
# Log in with your email in the browser; the CLI finishes automatically.

npx xdcai@latest call GET "https://api.xdcai.tech/x402/connect/<serviceId>/<path>"
npx xdcai@latest wallet balance

The login link expires in 10 minutes and is single-use. Under the hood the CLI starts a pairing, you complete it in the browser, and the CLI polls until it receives a 24-hour session token (auto-refreshed for 90 days).

3. API key (headless / custom clients)​

For agents that cannot open a browser (some custom MCP clients, scripts, or headless runners), mint an API key.

  1. Go to xdcai.tech/account and open the API keys section (under "Add wallet to agent").
  2. Click generate, optionally name it. The key is shown once - copy it now. It starts with xdcai_.
  3. Give it to the client as a bearer token:
Authorization: Bearer xdcai_your_key_here

The key can read your wallet and pay for services and approved payees. It cannot add payees or change limits (those are browser-only, so a leaked key can never widen its own access). Revoke a key any time from the same page; it stops working immediately. Keys are stored only as a hash - we cannot show a key again after it is created.

Which should I use?​

AgentUse
Claude.ai, ChatGPT (MCP)OAuth connector (api.xdcai.tech/mcp)
Claude Code, Cursor, Codex, shellnpx xdcai login
Headless / custom clientAPI key (xdcai_...)

Whatever you choose, set a spending limit first so the agent has a hard, on-chain ceiling.