Quickstart

Email OTP onboarding via Agent CLI or MCP. Discover the catalog, preflight, and run your first intent.

TL;DR: Integrate via Agent CLI or MCP with email OTP. You get an agent API key and execution wallets without the Creator Platform.

Architecture: See Architecture for the flow before diving in.

Email onboarding (CLI or MCP)

For AI agents: Use llms.txt for docs discovery, or llms-full.txt for the full API spec in one file (Execute Intent + x402). Read one first.

CLI:

thirdfy-agent login email you@example.com --json
thirdfy-agent login email you@example.com --code "<otp>" --accept-terms --key-name "My Agent" --json

MCP: startEmailOnboarding → completeEmailOnboarding (acceptTerms: true).

2. Confirm credentials

CLI: thirdfy-agent whoami --json (stores agentApiKey, owner session, executionWallets).

MCP: Response may include agent credentials; then getWalletProfile.

3. Discover actions

CLI: thirdfy-agent actions --json

MCP: getActionsCatalog or getProviderActions

Public catalog (no auth):

curl "https://api.thirdfy.com/api/v1/agent/actions/catalog"

4. Preflight

CLI: thirdfy-agent preflight --run-mode agent_wallet ...

MCP: preflight tools before your first write.

5. Execute

CLI: thirdfy-agent run --run-mode agent_wallet ...

MCP: walletExecute or agentRun

Fund the execution wallet for your venue before live writes.

6. Poll status

CLI: thirdfy-agent intent-status --intent-id <id> --json

MCP: getIntentStatus

HTTP:

curl "https://api.thirdfy.com/api/v1/agent/execute-intent/status?intentId=<intentId>"

Details: Quick start · CLI authentication · MCP onboarding

Full Example: Success and Rejection

Success response (HTTP 200):

{
  "intentId": "int_abc123",
  "status": "pending",
  "action": "swap",
  "chainId": 8453
}

Poll GET /api/v1/agent/execute-intent/status?intentId=int_abc123 until status is completed or failed.

Rejection response (HTTP 4xx):

{
  "error": "INTENT_REJECTED",
  "message": "Action 'swap' not in agent allowlist",
  "code": "ACTION_NOT_ALLOWED"
}

Common rejection reasons: invalid API key, action not in allowlist, params mismatch, estimatedAmountUsd exceeds policy limit. See Troubleshooting for remediation.

Environment: Set THIRDFY_API_URL=https://api.thirdfy.com (production) or https://api-test.thirdfy.com (testnet). Export THIRDFY_AGENT_API_KEY from email onboarding (whoami or MCP response). Credits: Delegated users pay for execution. See Credits for Users.

llms.txt / llms-full.txt: llms.txt = docs discovery. llms-full.txt = full API spec in one file.
Troubleshooting: Common errors and fixes
FAQ: Common questions