Authentication

Sign in once and the CLI saves your session. Already have a Thirdfy agent? Sign in with your browser. New to Thirdfy? Use the email code, which also creates your agent. Agent runtimes and CI can skip sign-in and use keys instead.

What the CLI uses

The CLI works with three credentials. You can pass each one as a flag, set it as an environment variable, or let login save it in ~/.thirdfy/config.json. If you set more than one, a flag wins over the environment, and the environment wins over the saved config.

Sign in one of the ways below.

Sign in with your browser

thirdfy-agent login opens the Thirdfy sign-in page, the same one Claude and ChatGPT use:

# Read access
thirdfy-agent login

# Read and trade access
thirdfy-agent login --trade

1. Sign in with the same method you use on thirdfy.com (email, Google or wallet).
2. Pick the agent the CLI acts for.
3. Approve. The browser hands the sign-in back to the CLI.

Without --trade, the CLI can read but not move funds; a write asks you to sign in again with --trade. On a machine without a browser, add --no-browser and open the printed link yourself. thirdfy-agent whoami shows the sign-in, and thirdfy-agent logout ends it. Needs CLI 0.5.0 or later.

1. Email code (recommended for new users)

Thirdfy emails you a one-time code. You send it back to finish signing in.

# Step 1: send the code
thirdfy-agent login email you@example.com --json

# Step 2: verify, accept terms, create the agent and its wallets
thirdfy-agent login email you@example.com --code "<otp>" --accept-terms --key-name "My Agent" --json

thirdfy-agent whoami --json
thirdfy-agent wallet list --json
thirdfy-agent help onboarding --json

Step 2 saves these in ~/.thirdfy/config.json:

• your owner session
• a new agent API key, when this is your first sign-in
• the agent's execution wallets (executionWallets), with a base58 Solana address next to the EVM one
• the default run mode agent_wallet for a new profile

Before you run a write, fund the execution wallet for your target chain. Do not fund the email login wallet. It is for sign-in only.

To see your wallets, run thirdfy-agent wallet profile --json. It reads the live state from the API. wallet list shows only what is saved on your machine.

In scripts, put --not-interactive (or --ni) after login email. Then missing input fails instead of waiting for a prompt.

2. Wallet signature

Use this when you, the owner, want to sign in with your own wallet instead of email.

thirdfy-agent agent auth challenge --agent-key "0xYOUR_AGENT_KEY" --json
# Sign challenge.message with the wallet, then verify:
thirdfy-agent agent auth verify --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json

verify returns an owner session. Pass it with --owner-session-token, for example to agent register --name "my-agent".

To save the session instead, run login with the same --challenge-id, --signature and --agent-key. To print the whole flow, run thirdfy-agent help onboarding --path wallet_sign --json.

3. Tokens you already have

If you already have an auth token, an owner session or an agent API key, save them once:

thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-api-key "$THIRDFY_AGENT_API_KEY" --json
thirdfy-agent whoami --json

login also takes these flags:

Execution-only mode

Use this mode in CI or an agent runtime, where nobody signs in. Set two environment variables:

• THIRDFY_AGENT_API_KEY, the agent API key
• THIRDFY_AGENT_KEY, the agent's 0x address

With both set, you can run actions, preflight, preview, run and intent-status. If you set only the API key, commands fail with MISSING_USER_DID.

To set this up in a runtime, see Hermes and OpenClaw.

Sign out

thirdfy-agent logout --json        # clear the local config
thirdfy-agent logout --all --json  # also revoke the owner session on the server

Credits and gas

Your Thirdfy credits and free daily requests decide whether a run is allowed. Network gas is separate. Thirdfy sponsors it where the chain and action support it.

To check your credits, run thirdfy-agent credits balance --json.

For the credentials each command needs, see CLI command reference: Authentication model.