Connect your agent (hosted MCP)

There are three ways to give an agent Tally tools. Pick by what your agent can do:

Your agent…	Use	What it feels like
Chats + makes web requests (Hermes, OpenClaw, most LLM agents)	Device flow (this page)	Agent shows you a link → you approve in the browser → done. No localhost.
Controls its own browser (Claude Desktop, ChatGPT, Cursor via a bridge)	Native MCP OAuth	A browser popup opens automatically; you approve.
Runs a local subprocess	Stdio + API key	Paste a key into config. See Connect via stdio.

The device-flow and browser-popup paths connect to the hosted endpoint, which exposes seven tools — pay_x402_service, pay_direct, get_wallet_info, get_wallet_balance (live on-chain USDC balance), check_x402_price (preview a service’s cost without paying), list_x402_services (discover paid services via the x402 Bazaar), and list_recent_payments — all bounded by the per-tx and daily caps you set in Tally. (The stdio package exposes the four core tools.) If you’re not sure, use the device flow — it works for any agent that can make HTTP requests, including chat-only ones.

Fastest path: paste this into your agent

This drives the device flow, which works regardless of host (it doesn’t need your agent to open a browser or run a local listener). It then points the agent at /skill.md so it knows how to use the wallet right after connecting — not just that it has one.

Connect yourself to Tally using its OAuth Device Flow so you can hold and spend
USDC on my behalf. Tally base URL: https://app.tallyforagents.com

1. Register a client (once):
   POST /oauth/register
   JSON: {"client_name":"My Agent","redirect_uris":["http://127.0.0.1/cb"],"scope":"wallet:read wallet:transfer x402:pay"}
   Save the returned client_id.

2. Start the device flow:
   POST /oauth/device_authorization
   form body: client_id=<client_id>&scope=wallet:read wallet:transfer x402:pay
   It returns verification_uri_complete, device_code, and interval.

3. Show me ONE line, then wait — do not show the raw code:
   "Click here to connect Tally and approve: <verification_uri_complete>"

4. After I tell you I've approved, poll for the token:
   POST /oauth/token
   form body: grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=<device_code>&client_id=<client_id>
   - {"error":"authorization_pending"} → wait <interval> seconds, then retry.
   - {"error":"slow_down"} → wait a few extra seconds, then retry.
   - When you receive an access_token, stop polling and save it.

5. Fetch https://app.tallyforagents.com/skill.md and follow it as your guide for
   every Tally action — checking balance, spending limits, payments, and history.
   Use the access_token as your Bearer credential (not an API key).

6. Confirm: GET /v1/me with header Authorization: Bearer <access_token>, and tell
   me the workspace, mode, and wallet limits it returns.

From now on, for anything money- or wallet-related, use the Tally REST endpoints
from that skill — don't invent endpoints.

What you’ll experience

The agent shows you a single link like https://app.tallyforagents.com/device?code=WDJB-MJHT. You:

Click it (it’s your own Tally domain).
Sign in if needed, pick the workspace, mode (test/live), and agent.
Click Authorize → you see “Connected — return to your agent.”

The agent’s polling finishes on its own a few seconds later. You never type the code — it’s embedded in the link; the visible code is just a fallback for typing it manually at https://app.tallyforagents.com/device.

This is the same pattern as gh auth login, the AWS CLI, and signing into apps on a smart TV. For a chat-based agent it’s the simplest flow possible — the “popup opens by itself” experience requires an agent that controls its own browser (see below).

If your host drives its own browser and can catch an OAuth redirect (Claude Desktop, ChatGPT, or Cursor via the mcp-remote bridge), point it at the hosted endpoint and you get the automatic popup instead of a code:

https://app.tallyforagents.com/mcp

It’s a standard OAuth 2.1 protected resource: an unauthenticated request gets a 401 + WWW-Authenticate pointing at /.well-known/oauth-protected-resource/mcp, which the host follows to open the consent screen. On Hermes builds that support remote-MCP OAuth:

hermes mcp add tally --url https://app.tallyforagents.com/mcp
hermes mcp login tally     # opens the browser → pick workspace → authorize
hermes mcp test tally
hermes gateway restart

If your host only prints a link instead of opening the browser and catching the response, it can’t complete this flow — use the device flow above instead. That’s the common case for chat-based agents.

The endpoint also accepts a static API key (tly_test_… / tly_live_…) as a bearer token, the same credential the stdio server takes.

The OAuth endpoints

Everything is advertised at the discovery document, so a host can wire itself up:

GET https://app.tallyforagents.com/.well-known/oauth-authorization-server

Endpoint	Purpose
`/oauth/register`	Dynamic client registration (RFC 7591) → `client_id`.
`/oauth/device_authorization`	Start the device flow (RFC 8628) → `device_code` + `user_code`.
`/oauth/authorize`	Browser consent for the redirect/popup flow.
`/oauth/token`	Exchange a code / device_code, or refresh.
`/oauth/revoke`	Disconnect (revokes the whole session).

Scopes: wallet:read, wallet:transfer, x402:pay. Moving money requires wallet:transfer. See OAuth 2.1 for the full protocol.

Grant a wallet permission

On first connect the agent has the tools but no spending power — Tally is non-custodial, so you authorize a wallet explicitly. Ask the agent “what’s my wallet?” (it calls get_wallet_info); it returns a dashboard URL. Open it, Grant permission, pick a funded wallet, set the per-tx + daily caps, and approve via passkey. Grants are mode-scoped — a test-mode grant won’t show in live mode.

Switching workspaces

The token is bound to the workspace you picked, so switching is a re-auth: run the connect flow again and choose a different workspace, or revoke first via /oauth/revoke (on Hermes, hermes mcp logout tally).

Skill install (Hermes / OpenClaw)

For hosts that use a skill manifest instead of (or alongside) MCP, Tally publishes one:

hermes skills install https://www.tallyforagents.com/skill.md

The skill is API-key based: it collects a TALLY_API_KEY and teaches the agent to call Tally’s REST API directly. Use the device flow above when you want OAuth (no key); use the skill when you want “install + paste a key.”

What’s happening under the hood

Every entry point runs the same enforcement: the Tally policy check (caps, allowlists, expiry) then Privy’s secure-enclave signature. The MCP/OAuth layer can’t widen those caps.
The access token only ever sees the workspace + mode you chose on the consent screen, and it expires (the agent silently refreshes).
Payments show up in the dashboard’s Transactions tab with the same metadata as SDK or stdio calls.

Get started

Concepts

Guides

API reference

SDK reference

Ops

Resources

Connect your agent (hosted MCP)

Fastest path: paste this into your agent

What you’ll experience

The OAuth endpoints

Grant a wallet permission

Switching workspaces

Skill install (Hermes / OpenClaw)

What’s happening under the hood

See also

​Fastest path: paste this into your agent

​What you’ll experience

​Native browser popup (browser-driving hosts)

​The OAuth endpoints

​Grant a wallet permission

​Switching workspaces

​Skill install (Hermes / OpenClaw)

​What’s happening under the hood

​See also

Fastest path: paste this into your agent

What you’ll experience

Native browser popup (browser-driving hosts)

The OAuth endpoints

Grant a wallet permission

Switching workspaces

Skill install (Hermes / OpenClaw)

What’s happening under the hood

See also