Run a Hermes agent on Thirdfy

Give a Hermes agent its own Thirdfy agent key, provision the Agent CLI before the runtime starts, check it at startup, and let it trade from its own wallet within its limits.

Your Hermes agent runs shell commands, so the Agent CLI is the simplest way to give it Thirdfy. You get the agent's keys once, store them as runtime secrets, and install the CLI in the runtime. Every command returns JSON the agent can read. Then it reads markets, checks venues and trades from its own wallet, within the limits you set.

The quickest way to start is to give your agent this prompt. It sets itself up with the CLI.

Read https://docs.thirdfy.com/agents.md and set up Thirdfy for me with the Thirdfy Agent CLI.

What you need

  • A Hermes runtime that can run shell commands and Node.js packages.
  • A Thirdfy agent and its keys. Step 1 shows how to get them.
  • Funds in the agent's execution wallet, if you want it to trade. It can read without them.

1. Get an agent and its keys

You do this once, on your own machine. Sign in by email. The second command creates the agent and its wallets.

npm install -g @thirdfy/agent-cli
thirdfy-agent login email you@example.com --json
thirdfy-agent login email you@example.com --code "<otp>" --accept-terms --json
thirdfy-agent whoami --json

Already have a Thirdfy agent? thirdfy-agent login --trade signs in with your browser instead. You pick the agent and approve.

The runtime needs two values from this sign-in:

SecretWhere to find it
THIRDFY_AGENT_API_KEYThe agent key (agent-...), saved in ~/.thirdfy/config.json under agent.apiKey
THIRDFY_AGENT_KEYThe agent's 0x address, shown by whoami as agent.agentKey

You can also create an agent over MCP, without the CLI. Call startEmailOnboarding and completeEmailOnboarding on https://mcp.thirdfy.com/mcp/public. The key is returned once, at data.bootstrap.agentApiKey.

2. Store the keys as runtime secrets

Save both values in the Hermes runtime's secrets. Never put them in prompts or skill files.

3. Provision the CLI before Hermes starts

Install the CLI in the runtime and pin the version, so a new release never changes your agent without warning:

npm install -g @thirdfy/agent-cli@0.5.0

Set the environment before the Hermes dashboard or runtime starts:

THIRDFY_AGENT_API_KEY=agent-...        # from your secret store
THIRDFY_AGENT_KEY=0x...                # the agent's 0x address
THIRDFY_RUN_MODE=agent_wallet          # the agent trades from its own execution wallet

With these set, the runtime does not need to sign in. If THIRDFY_AGENT_KEY is missing, runs fail with MISSING_USER_DID.

4. Check at startup

Run these checks as part of the runtime's health check:

thirdfy-agent --version --json
thirdfy-agent doctor certify execution --json
thirdfy-agent doctor auth --json
thirdfy-agent doctor self --json

doctor certify execution checks the CLI version and command set, and changes nothing. doctor auth checks the sign-in, and doctor self checks the signer. If a check fails, stop the runtime.

5. Make a first read

thirdfy-agent actions --provider hyperliquid --json
thirdfy-agent run --action get_openmarket_btc_funding --provider openmarket --json

actions lists what the agent may call. Have it run this before it plans. From each response, read success, code and data.

6. Preview, then run a trade

The agent trades from its own execution wallet (agent_wallet). Fund that wallet for your target chain, not your login wallet. thirdfy-agent wallet profile --json shows it.

Check the venue, then preflight the trade:

thirdfy-agent venue readiness hyperliquid --json
thirdfy-agent preflight --action place_hyperliquid_perps_order --provider hyperliquid \
  --params '{"coin":"ETH","isBuy":true,"size":0.01,"limitPx":2000,"orderType":"limit"}' --json

Go on only when venue readiness says ready: true and blockingReasons is empty.

Then run it. This places a real order:

thirdfy-agent run --action place_hyperliquid_perps_order --provider hyperliquid \
  --params '{"coin":"ETH","isBuy":true,"size":0.01,"limitPx":2000,"orderType":"limit"}' \
  --idempotency-key "cycle-2026-10-08T14:00Z-eth" --confirm-writes --json

A write needs --confirm-writes. Give each decision its own stable --idempotency-key. Then a retried cycle never places the same order twice.

What happens before every trade

  • Your agent's limits apply. Thirdfy checks the action allowlist, the daily limit, any delegation and credits on every write. If one check fails, nothing runs.
  • Venues are checked. Thirdfy refuses a venue order when the venue isn't ready, and says why.
  • Retries are safe. The same --idempotency-key never places the same order twice.
  • The right wallet. Use agent_wallet for the agent's own wallet. Switch to thirdfy only to act across many delegated wallets at once (fan-out).

If something goes wrong

What you seeWhat to do
MISSING_USER_DIDSet THIRDFY_AGENT_KEY to the agent's 0x address
401 or auth errorsCheck that THIRDFY_AGENT_API_KEY is set in the runtime, not only on your machine
A startup check failsStop the runtime. Check the pinned CLI version and the secrets
blockingReasons from venue readinessFund or set up the venue first. See the venue's integration page
403 ... is not allowedThe action is not on the agent's allowlist. Allow it for the agent, or pick another action
POLICY_DAILY_LIMITThe agent's daily limit is used up
DAILY_FREE_LIMIT_EXCEEDEDThe agent's credits, today's free requests and the owner's credits are all used. Check with thirdfy-agent credits balance --json, then buy credits with thirdfy-agent credits buy --usd <amount> --json or top up at thirdfy.com/credits

For developers

Package@thirdfy/agent-cli, pinned to 0.5.0 in the runtime
SecretsTHIRDFY_AGENT_API_KEY (agent-...), THIRDFY_AGENT_KEY (0x...)
Run modeTHIRDFY_RUN_MODE=agent_wallet
Hosted on EarnOrgAlso set THIRDFY_EXECUTION_RUNTIME_ID and THIRDFY_EXECUTION_ORG_ID. The CLI sends them with every write, so credits and history count toward the right runtime and organization
Onboarding helpthirdfy-agent help onboarding --json

Hermes can also connect over MCP. Point the connector at https://mcp.thirdfy.com/mcp and send Authorization: Bearer ${THIRDFY_AGENT_API_KEY} as a header. See OpenClaw and Hermes (MCP).

Related

Run an OpenClaw agent on Thirdfy
Give an OpenClaw agent its own Thirdfy agent key, store it as a runtime secret, connect it over MCP, and let it read markets and trade from its own wallet within its limits.
Guides
Step-by-step walkthroughs you can share. Each guide takes you from zero to one result, with real screenshots and example prompts.