Thirdfy Agent CLI

Thirdfy Agent CLI

Use the thirdfy-agent CLI to onboard agents, discover actions, run governance preflight checks, queue execute-intent requests, and poll status with stable JSON output.

Install

npm install -g @thirdfy/agent-cli
thirdfy-agent --version --json

Or use directly:

npx @thirdfy/agent-cli --help

Authentication model

There are three credentials with different trust scopes:

Set them in your shell:

export AGENT_API_KEY="..."
export THIRDFY_AUTH_TOKEN="..."
export THIRDFY_OWNER_SESSION_TOKEN="..."

Execution-only mode (no user auth token at runtime)

If you already have a valid AGENT_API_KEY, you can run execute-intent flows without THIRDFY_AUTH_TOKEN.

Use this mode for:

• agent-controlled execution workers
• bots that only do action discovery + preflight + run + intent-status
• integrations where onboarding/admin steps are handled separately

In this mode, use:

export AGENT_API_KEY="..."

thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --idempotency-key "exec-only-001" --json

By default, thirdfy-agent uses production (https://api.thirdfy.com). Use --api-base only for staging/dev/custom deployments.

THIRDFY_AUTH_TOKEN is still required for account-scoped commands such as credits balance, delegation *, and credentials *.

For onboarding owner operations (agent register, agent key *), you can use either:

• THIRDFY_AUTH_TOKEN (Privy-native path), or
• THIRDFY_OWNER_SESSION_TOKEN (wallet-sign path)

Which token does each command need?

Quickstart flow

1) Discover catalogs and actions

thirdfy-agent catalogs list --json
thirdfy-agent actions --json

Policy-aware action view:

thirdfy-agent actions \
  --agent-api-key "$AGENT_API_KEY" \
  --json

2) Governance preflight

thirdfy-agent preflight \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' \
  --estimated-amount-usd 25 \
  --json

3) Queue execution intent

thirdfy-agent run \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' \
  --estimated-amount-usd 25 \
  --idempotency-key "swap-2026-03-26-001" \
  --json

Run mode selection (thirdfy / self / hybrid)

The same command surface supports three execution topologies:

• --run-mode thirdfy: Thirdfy-governed execute-intent (default for profile=network)
• --run-mode self: self-custody unsigned transaction flow (default for profile=personal)
• --run-mode hybrid: self-custody + governance mirror metadata (default for profile=builder)

Profile/run-mode precedence:

1. CLI flag (--run-mode)
2. env (THIRDFY_RUN_MODE)
3. saved profile config (~/.thirdfy/config.json)
4. profile defaults

thirdfy-agent profile init --profile personal --json
thirdfy-agent profile use --profile builder --run-mode hybrid --json
thirdfy-agent whoami --json

profile use --profile <name> reapplies that profile's default run mode unless you explicitly pass --run-mode.

Jeff aliases (same rails, faster UX)

thirdfy-agent jeff preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --run-mode self --json
thirdfy-agent jeff trade --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --run-mode hybrid --json
thirdfy-agent jeff status --intent-id "<intentId>" --json
thirdfy-agent prompt "swap USDC to WETH with low slippage"

CLI comparison: Thirdfy vs Bankr vs Boba

Thirdfy is designed to keep a simple operator experience (swap, preflight, run) while adding governance and protocol safety rails.

Practical takeaway:

• If you want a single CLI command standard and governance-backed execution, use Thirdfy as the control plane.
• If you already use Bankr/Boba style agents, you can still route execution through Thirdfy via AGENT_API_KEY + delegation readiness.

Using delegation with external agents (Bankr/Boba-style)

You can keep your own agent runtime and still integrate with Thirdfy governance/protocol:

1. Onboard/own the agent (agent register using Privy or wallet-sign owner auth).
2. Set delegation readiness (delegation create, delegation activate, delegation status).
3. Set venue credentials if required (credentials upsert, credentials status).
4. Discover allowed actions with policy-aware actions --agent-api-key.
5. Gate every trade through preflight.
6. Execute via run with idempotency and monitor via intent-status.

This gives external agents:

• their own UX/runtime,
• plus Thirdfy governance controls,
• plus protocol-level attribution/incentive alignment.

Delegation storage model (recommended)

For delegated execution lanes, use a hybrid model:

• Onchain is the authority for execution validity (delegation manager checks signature/delegate/expiry/revocation).
• Thirdfy infra stores delegation state for routing, preflight, and auditing.

What to store in Thirdfy infra (recommended):

• userDid, agentKey, chainId, walletAddress
• delegationManager, sessionAccountAddress, sessionAccountType
• permissionsContext (or equivalent hash/context id)
• permissionsExpiry
• signed delegation payload (for deterministic replay/verification and audit)
• status lifecycle (active, revoked, timestamps, revoke reason)

What not to store:

• private keys, seed phrases, OTP codes, or signer secrets
• raw long-lived exchange secrets in plaintext

Practical rule:

• Store enough metadata to make delegation checks deterministic in preflight/run.
• Re-verify effective validity against current chain state before execution in Thirdfy-managed lanes.

This matches advanced-permission style delegated execution patterns: infra tracks and indexes delegation state, while cryptographic validity remains enforceable by signed payload + onchain validation.

Add your agent to Thirdfy governance + protocol

To make an external agent participate in Thirdfy rails (not only call raw actions):

• Register the agent identity (agent register).
• Keep owner auth active for lifecycle operations (agent key rotate / revoke).
• Configure delegation and credential readiness for your target venues/chains.
• Use policy-aware discovery and preflight before execution.
• Use stable idempotency keys in production workers.

This path lets your agent:

• operate under Thirdfy governance checks,
• interoperate with protocol actions safely,
• and evolve from standalone execution into protocol-native participation.

4) Poll intent status

thirdfy-agent intent-status \
  --intent-id "<intentId>" \
  --json

Onboarding and key lifecycle

Choose one onboarding owner-auth mode:

Path A: Privy-native owner auth

thirdfy-agent agent register \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0x..." \
  --name "my-agent" \
  --json

Path B: Wallet-sign owner auth

thirdfy-agent agent auth challenge \
  --agent-key "0xYOUR_AGENT_KEY" \
  --json

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

# Export owner session from verify response
export THIRDFY_OWNER_SESSION_TOKEN="owner-..."

thirdfy-agent agent register \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --name "my-agent" \
  --json

Rotate/revoke API key with either owner auth mode:

thirdfy-agent agent key rotate --agent-key "0x..." --auth-token "$THIRDFY_AUTH_TOKEN" --json
thirdfy-agent agent key revoke --agent-key "0x..." --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --json

Create an OpenClaw agent with the CLI

Use this path when you want a practical, command-line-only onboarding flow for OpenClaw.

Prerequisites

• Either THIRDFY_AUTH_TOKEN (Privy path) or THIRDFY_OWNER_SESSION_TOKEN (wallet-sign path) for owner onboarding operations.
• A wallet address for --agent-key (this is the agent identity).
• API environment with onboarding enabled (local/staging/production policy dependent).

Step 1) Prove owner identity (choose one mode)

Privy-native:

export THIRDFY_AUTH_TOKEN="..."

Wallet-sign:

thirdfy-agent agent auth challenge --agent-key "0xYOUR_AGENT_KEY" --json
# Sign challenge.message and verify signature:
thirdfy-agent agent auth verify --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
export THIRDFY_OWNER_SESSION_TOKEN="owner-..."

Step 2) Register the agent

thirdfy-agent agent register \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --name "openclaw-my-agent" \
  --json

Or wallet-sign:

thirdfy-agent agent register \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --name "openclaw-my-agent" \
  --json

Step 3) Get and verify the agent API key

After registration/approval, copy agentApiKey from the response or Creator Platform and export it:

export AGENT_API_KEY="..."
thirdfy-agent actions \
  --agent-api-key "$AGENT_API_KEY" \
  --json

If this succeeds, the agent key is active for policy-aware action discovery.

Step 4) Check delegation readiness

thirdfy-agent delegation status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --json

If required by your governance mode, configure delegation:

thirdfy-agent delegation create \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --owner-address "0xOWNER_WALLET" \
  --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
  --max-usd-per-day 250 \
  --json

# Sign the returned data.delegation payload in the owner wallet, then:
thirdfy-agent delegation activate \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --wallet-address "0xOWNER_WALLET" \
  --session-account-address "0xSESSION_ACCOUNT" \
  --delegation-manager "0xDELEGATION_MANAGER" \
  --delegation '{"delegator":"0x...","delegate":"0x...","authority":"0x...","caveats":[],"salt":"0x...","signature":"0x"}' \
  --signature "0xSIGNED_DELEGATION" \
  --json

Step 5) Check venue credential readiness (if action requires it)

thirdfy-agent credentials status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --venue bitfinex \
  --json

Step 6) Run first OpenClaw flow (preflight -> run -> intent-status)

thirdfy-agent preflight \
  --agent-api-key "$AGENT_API_KEY" \
  --action claim-ichi-bribes \
  --params '{"gauge":"0x...","recipient":"0x..."}' \
  --estimated-amount-usd 25 \
  --json

thirdfy-agent run \
  --agent-api-key "$AGENT_API_KEY" \
  --action claim-ichi-bribes \
  --params '{"gauge":"0x...","recipient":"0x..."}' \
  --estimated-amount-usd 25 \
  --idempotency-key "openclaw-first-run-001" \
  --json

Then poll the returned intentId:

thirdfy-agent intent-status \
  --intent-id "<intentId>" \
  --json

Delegation and credentials checks

thirdfy-agent delegation status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0x..." \
  --json

thirdfy-agent credentials status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --venue bitfinex \
  --json

Troubleshooting

• Invalid agent API key -> validate AGENT_API_KEY, agent approval state, and action allowlist.
• Authentication required or Invalid Privy token -> refresh THIRDFY_AUTH_TOKEN.
• Missing required onboarding schema (...) -> backend migration is missing; apply latest onboarding DB migration before using wallet-sign owner auth.
• SELF_MODE_NO_FANOUT -> self run-mode cannot use delegated execute-intent fanout; use self build-tx/unsigned transaction flow.
• DELEGATION_MISSING -> Thirdfy-managed lane (thirdfy or hybrid mirror) has no active delegation/subscriber context.
• POLICY_BLOCKED -> governance preflight denied one or more subscribers; inspect blockedByReason and results.
• PROVIDER_UNAVAILABLE -> selected action/provider does not support execute-intent rail for this lane.
• PREFLIGHT_BLOCKED -> check governance fields (blocked, blockedByReason, results).
• INTENT_NOT_FOUND -> confirm intentId and environment match (production vs staging/dev API base).
• capabilitiesVersion: null in meta -> target API may not expose /api/v1/agent/cli/capabilities yet.

Related

• Execute Intent API
• Actions Reference
• Actions List
• Create OpenClaw agent with CLI
• Creator Platform