# Thirdfy API - Full Documentation

> Thirdfy is the governance layer for autonomous capital. Any DeFi agent can be validated here. Build agents, execute intents, earn emissions. Agent Creators build agent brains that send Execute Intents to Thirdfy. Thirdfy validates, users delegate, execution is safe.

## LLM File Options

- **llms.txt** (https://docs.thirdfy.com/llms.txt) — Curated map. Use when you need to discover docs structure or navigate to specific pages. Lightweight.
- **llms-full.txt** (this file) — Full API spec inline. Use when you need to call the Execute Intent API or x402 API directly. One fetch = complete API reference.

---

## Contact

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

---

## Base URL

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

---

## Execute Intent API

Submit and track intents for registered agents. Use this API to integrate your AI agent with Thirdfy's Execute Intent platform.

**Authentication:** Pass your `agentApiKey` from Creator Platform (https://thirdfy.com/creator) → Identity tab. Register and claim your agent first.

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

Get the full action catalog with schema, params, and metadata. **No authentication required.** Use this to discover all available actions and their parameters. Always up to date.

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

Response includes: `actions[]` (action, aliases, description, requiredParams, paramsSchema, maxAmountUsd, supportsExecuteIntent, supportsBuildTx), `providerFamilies[]`, `generatedAt`.

**Example flow:** 1) GET /actions/catalog to discover actions and params. 2) Build params from requiredParams + paramsSchema. 3) POST /execute-intent with action, params, chainId. 4) Poll GET /execute-intent/status.

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

List allowed actions for your agent. Use this to discover which actions (swap, vote, claim, etc.) your agent can request. Omit agentApiKey for full list.

**Query parameters**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| agentApiKey | string | Yes | Your API key from Creator Platform |

**Example**

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

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

Submit an intent. Thirdfy validates policy, limits, and allowed actions, then fans out to delegated users.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| agentApiKey | string | Yes | Your API key |
| action | string | Yes | Action type (e.g. swap, vote, claim) |
| params | object | Yes | Action-specific parameters |
| chainId | number | Yes | Chain ID (e.g. 8453 for Base) |
| estimatedAmountUsd | number | No | Estimated USD value for policy limits |
| idempotencyKey | string | No | Unique key to prevent duplicate submissions |

**Example: Swap**

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

**Success response (HTTP 200)**

```json
{
  "success": true,
  "intentId": "int_abc123",
  "status": "queued",
  "total": 0,
  "executed": 0,
  "results": []
}
```

Poll status until `status` is `completed` or `failed`. Completed response:

```json
{
  "success": true,
  "intentId": "int_abc123",
  "status": "completed",
  "total": 3,
  "executed": 3,
  "results": [
    {
      "userDid": "did:privy:...",
      "walletAddress": "0x...",
      "chainId": 8453,
      "success": true,
      "txHash": "0x..."
    }
  ]
}
```

**Rejection response (HTTP 4xx)**

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

### GET /api/v1/agent/execute-intent/status

Poll intent status. Call until `status` is `completed` or `failed`.

**Query parameters**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| intentId | string | Yes | Intent ID from execute-intent response |

**Example**

```bash
curl "https://api.thirdfy.com/api/v1/agent/execute-intent/status?intentId=int_abc123"
```

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

Build an unsigned transaction for user to sign locally (Model B, non-custodial flow).

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| agentApiKey | string | Yes | Your API key |
| action | string | Yes | Action type |
| params | object | Yes | Action-specific parameters (may include recipient for swap output) |
| chainId | number | Yes | Chain ID |
| walletAddress | string | No | Wallet address that will sign (some actions use recipient in params) |

**Example**

```bash
curl -X POST "https://api.thirdfy.com/api/v1/agent/build-tx" \
  -H "Content-Type: application/json" \
  -d '{
    "agentApiKey": "YOUR_API_KEY",
    "action": "swap",
    "params": {
      "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000",
      "recipient": "0x..."
    },
    "chainId": 8453,
    "walletAddress": "0x..."
  }'
```

---

## x402 API

Autonomous payment integration for external AI agents. No API key required. Authentication is handled through on-chain USDC payments on Base.

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

Find Thirdfy's x402 service metadata. Returns available credit packages and payment details.

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

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

Purchase credits using x402 protocol.

```bash
POST https://api.thirdfy.com/api/v1/credits/buy-with-x402
Content-Type: application/json

{
  "sku": "credits_1000",
  "userAddress": "0xYOUR_WALLET_ADDRESS"
}
```

**Credit Packages**

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

**Payment Flow**

1. First call returns HTTP 402 with payment challenge:

```json
{
  "x402Challenge": {
    "invoiceId": "inv_credits_1000_abc123",
    "amount": "18",
    "recipient": "0x572D1443f0aAfd492E396516ED26Dc269C516fd7",
    "currency": "USDC",
    "network": "base"
  }
}
```

2. Transfer USDC to the recipient address on Base.

3. Retry request with payment proof:

```bash
POST https://api.thirdfy.com/api/v1/credits/buy-with-x402
Content-Type: application/json
X-Payment-Receipt: 0xYOUR_TX_HASH
X-Invoice-Id: inv_credits_1000_abc123

{
  "sku": "credits_1000",
  "userAddress": "0xYOUR_WALLET_ADDRESS"
}
```

Response (HTTP 200):

```json
{
  "success": true,
  "credits": 1000,
  "balance": 1000,
  "message": "Successfully purchased 1000 credits"
}
```

**Payment Details**

- Currency: USDC on Base
- Network: Base (Chain ID 8453)
- Settlement: ~2 seconds
- Fees: No protocol fees
- Payment Address: 0x572D1443f0aAfd492E396516ED26Dc269C516fd7

---

## Links

- [llms.txt](https://docs.thirdfy.com/llms.txt) — Curated map. Use for docs discovery.
- [Execute Intent API](https://docs.thirdfy.com/api/execute-intent-api) — Full page with OpenClaw example
- [x402 API](https://docs.thirdfy.com/api/x402-api) — Full page with Python example
- [Quickstart](https://docs.thirdfy.com/agents/ai-agent-creators/quickstart) — Run your first intent with curl
- [Creator Platform](https://thirdfy.com/creator) — Register agents, get API keys
- [Troubleshooting](https://docs.thirdfy.com/agents/ai-agent-creators/troubleshooting) — Common errors and fixes