# Thirdfy — Agent integration reference

> Thirdfy validates finance agent intents before wallets execute. **Start with MCP or Agent CLI** (email OTP onboarding). Use this file for HTTP mirrors and x402 when you cannot call MCP tools. Site map: https://docs.thirdfy.com/llms.txt

## LLM file options

- **llms.txt** (https://docs.thirdfy.com/llms.txt) — Curated doc map. Prefer this for navigation.
- **llms-full.txt** (this file) — MCP summary + Execute Intent HTTP + x402 in one fetch.

---

## Contact

- Website: https://thirdfy.com
- Documentation: https://docs.thirdfy.com
- Community: https://discord.gg/thirdfy
- Creator Platform (optional): https://thirdfy.com/creator

---

## Authentication (read first)

**Default path:** email OTP onboarding issues an `agentApiKey` (usually `agent-...`) and managed execution wallets.

| Path | How |
|------|-----|
| **Agent CLI** | `thirdfy-agent login email you@example.com --json` then complete OTP. Docs: https://docs.thirdfy.com/documentation/agent-cli/authentication |
| **MCP** | `startEmailOnboarding` → `completeEmailOnboarding` (`acceptTerms: true`). Docs: https://docs.thirdfy.com/documentation/mcp/onboarding |
| **Creator Platform** (optional) | Web UI, directory, skills. Not required for first execution. |

**Simplest execution lane:** `runMode=agent_wallet` (your agent's managed wallet). No MetaMask delegation grant required for first writes.

Machine-readable steps: CLI `thirdfy-agent help onboarding --json` or MCP `describeOnboardingPath`.

---

## Thirdfy MCP (preferred)

Managed endpoint. No public repo. Streamable HTTP.

| Item | Value |
|------|--------|
| Base URL | `https://mcp.thirdfy.com` |
| MCP connector | `POST https://mcp.thirdfy.com/mcp` |
| Tool manifest | `GET https://mcp.thirdfy.com/tools` |
| Tool REST | `POST https://mcp.thirdfy.com/tool/<toolName>` |
| Health | `GET https://mcp.thirdfy.com/health` |

**Typical flow**

1. `getActionsCatalog` or `getProviderActions` (discovery)
2. `describeOnboardingPath` → `startEmailOnboarding` → `completeEmailOnboarding`
3. Preflight before live writes
4. `walletExecute` or `agentRun` (`runMode=agent_wallet`) or `executeIntent` (delegated fan-out)

**Core tools**

| Tool | Purpose |
|------|---------|
| `getActionsCatalog` | Live action catalog mirror |
| `getProviderActions` | Filter by provider (`hyperliquid`, `allora`, `trading`, …) |
| `describeOnboardingPath` | Email OTP steps for this host |
| `startEmailOnboarding` / `completeEmailOnboarding` | Issue agent API key + wallets |
| `getSelfReadiness` | Wallet and delegation readiness |
| `executeIntent` | Submit validated intent (fan-out lane) |
| `walletExecute` | Managed wallet execution |
| `agentRun` | Route by signer intent / runMode |
| `getThirdfyHelp` | Topic help (`frameworks`, onboarding, providers) |
| `brain_sections` | Console Brain lanes (Trading, Yield, Prediction) from warm snapshots |
| `brain_suggest_strategy` | Governed strategy detail and default prompt |
| `brain_quote_or_preflight` | Read-first preflight for a Brain strategy |
| `brain_prepare_earnclaw_handoff` | EarnClaw graduate handoff proposal (read-only) |

Docs: https://docs.thirdfy.com/documentation/mcp · Console Brain: https://docs.thirdfy.com/documentation/console/brain · Claude Managed Agents: https://docs.thirdfy.com/documentation/claude-managed-agents

**Smoke (no auth)**

```bash
curl -s https://mcp.thirdfy.com/tools
curl -s -X POST https://mcp.thirdfy.com/tool/getActionsCatalog \
  -H "Content-Type: application/json" -d '{}'
```

Credentialed tools: pass `agentApiKey` per tool policy (Bearer on REST `/tool/*` where required).

---

## API base URL

| Environment | Base URL |
|-------------|----------|
| Production | https://api.thirdfy.com |
| Testnet | https://api-test.thirdfy.com |

---

## Execute Intent API (HTTP mirror)

Use when you own a custom HTTP client. Prefer MCP or CLI for execution.

### GET /api/v1/agent/actions/catalog

Full action catalog. **No authentication required.**

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

Response includes: `actions[]`, `providerFamilies[]`, `generatedAt`.

### GET /api/v1/agent/actions

Allowed actions for your agent (requires `agentApiKey` query param).

```bash
curl "https://api.thirdfy.com/api/v1/agent/actions?agentApiKey=YOUR_AGENT_KEY"
```

### POST /api/v1/agent/execute-intent

Submit an intent. Thirdfy validates policy, limits, and allowlists before wallets execute.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| agentApiKey | string | Yes | From email OTP (CLI/MCP) or Creator Platform |
| action | string | Yes | Catalog action id |
| params | object | Yes | Action-specific parameters |
| chainId | number | Yes | e.g. 8453 (Base) |
| estimatedAmountUsd | number | No | Policy limits |
| idempotencyKey | string | No | Dedup key |

```bash
curl -X POST "https://api.thirdfy.com/api/v1/agent/execute-intent" \
  -H "Content-Type: application/json" \
  -d '{
    "agentApiKey": "YOUR_AGENT_KEY",
    "action": "swap",
    "params": {
      "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000"
    },
    "chainId": 8453,
    "estimatedAmountUsd": 25,
    "idempotencyKey": "swap-2026-03-01-001"
  }'
```

Poll: `GET /api/v1/agent/execute-intent/status?intentId=...`

### POST /api/v1/agent/build-tx

Unsigned transaction for local signing (Model B).

---

## x402 API

Buy credits with USDC on Base. No agent API key required for the payment challenge flow.

### GET /api/v1/credits/x402-metadata

```bash
curl "https://api.thirdfy.com/api/v1/credits/x402-metadata"
```

### POST /api/v1/credits/buy-with-x402

First call may return HTTP 402 with `x402Challenge`. Pay USDC on Base, retry with `X-Payment-Receipt` and `X-Invoice-Id`.

| SKU | Credits | Price (USDC) |
|-----|---------|--------------|
| credits_100 | 100 | 2.00 |
| credits_1000 | 1,000 | 18.00 |
| credits_10000 | 10,000 | 160.00 |

Payment address (Base USDC): `0x572D1443f0aAfd492E396516ED26Dc269C516fd7`

---

## Links

- [Console Brain](https://docs.thirdfy.com/documentation/console/brain) — Trading, Yield, Prediction start-of-chat lanes
- [Quick start](https://docs.thirdfy.com/documentation/quick-start) — Email OTP + agent_wallet path
- [Help and glossary](https://docs.thirdfy.com/documentation/help)
- [Agent CLI](https://docs.thirdfy.com/documentation/agent-cli)
- [MCP hub](https://docs.thirdfy.com/documentation/mcp)
- [Execute Intent API (full page)](https://docs.thirdfy.com/documentation/api/execute-intent-api)
- [x402 API (full page)](https://docs.thirdfy.com/documentation/api/x402-api)
- [Integrations](https://docs.thirdfy.com/documentation/integrations)
- [Troubleshooting](https://docs.thirdfy.com/documentation/creators/ai-agent-creators/troubleshooting)