Actions Reference

Full catalog of Execute Intent actions — schema, params, and examples. Always up to date from the API.

Actions Reference

The Actions Reference is the canonical list of all actions your agent can request via the Execute Intent API. It is kept up to date automatically — new skills and actions appear as soon as they are deployed.

Always current: Fetch the catalog from the API. The docs page you're reading is a guide; the live catalog is the source of truth.

Get the Action Catalog

GET /api/v1/agent/actions/catalog

Returns the full action catalog with schema, params, and metadata. No authentication required.

Environment	URL
Production	`https://api.thirdfy.com/api/v1/agent/actions/catalog`
Testnet	`https://api-test.thirdfy.com/api/v1/agent/actions/catalog`

Example

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

Response structure

{
  "generatedAt": "2026-03-05T12:00:00.000Z",
  "source": "action_catalog",
  "version": 1,
  "providerManifestVersion": 1,
  "providerFamilies": [
    {
      "providerId": "thirdfy",
      "providerKind": "internal",
      "capabilities": ["execute", "fanoutSafe", "readOnly"],
      "supportedChains": [8453, 84532],
      "custodyMode": "mixed",
      "description": "Thirdfy-native DeFi actions, governance rails, rewards."
    },
    {
      "providerId": "trading",
      "providerKind": "evmDex",
      "capabilities": ["quote", "execute", "readOnly"],
      "supportedChains": [1, 10, 137, 8453, 84532, 42161],
      "custodyMode": "mixed",
      "description": "Quote and execution for onchain trading."
    }
  ],
  "actions": [
    {
      "action": "swap",
      "aliases": ["swap"],
      "description": "Swap tokens via DEX routing.",
      "requiredParams": ["tokenIn", "tokenOut", "amountIn"],
      "paramsSchema": { "type": "object", "properties": { ... } },
      "maxAmountUsd": 50000,
      "requiresSubscription": true,
      "implementation": "agentkit",
      "enabled": true,
      "supportsExecuteIntent": true,
      "supportsExecute": true,
      "supportsBuildTx": true
    }
  ]
}

Catalog Structure

Each action in the catalog has:

Field	Type	Description
`action`	string	Canonical action name (e.g. `swap`, `claim_agent_gauge_emissions`)
`aliases`	string	Alternate spellings (snake_case, kebab-case)
`description`	string	Human-readable description
`requiredParams`	string	Required parameter keys
`paramsSchema`	object \| null	JSON Schema for params (type, properties, required)
`maxAmountUsd`	number \| null	Max USD value for policy limits (0 = read-only)
`requiresSubscription`	boolean	Whether user must delegate to agent
`implementation`	string	`agentkit` or `internal`
`enabled`	boolean	Whether action is active
`supportsExecuteIntent`	boolean	Model A (fan-out) supported
`supportsExecute`	boolean	Direct execute supported
`supportsBuildTx`	boolean	Model B (build unsigned tx) supported

providerFamilies describes action providers (thirdfy, trading, bridge, etc.) and their supported chains.

Example: End-to-End Flow

Use the catalog to discover actions and build valid requests:

# 1. Fetch the catalog (no auth)
CATALOG=$(curl -s "https://api.thirdfy.com/api/v1/agent/actions/catalog")

# 2. Inspect available actions (e.g. with jq)
echo "$CATALOG" | jq '.actions[] | {action, description, requiredParams}'

# 3. Pick an action and build params from requiredParams + paramsSchema
# Example: swap needs tokenIn, tokenOut, amountIn
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-05-001"
  }'

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

Input Key Format

You may submit either canonical kebab-case or compatibility snake_case; canonical keys are preferred. Example: deposit-ichi-vault and deposit_ichi_vault both resolve to the same action.

How to Use the Catalog

For AI agents

Fetch the catalog at startup or when building intents.
Match user intent to an action (e.g. "swap USDC for ETH" → swap).
Build params from requiredParams and paramsSchema.
Submit via POST /api/v1/agent/execute-intent (include idempotencyKey for write actions).

For developers

Discover actions — See all available actions and their schemas.
Validate params — Use paramsSchema to validate before submitting.
Check support — supportsExecuteIntent, supportsBuildTx indicate which flows are supported.

Example Actions (Common)

Action	Description	Key Params
`swap`	Swap tokens via DEX	`tokenIn`, `tokenOut`, `amountIn`
`vote`	Vote on gauges	`gaugeAddress`, `weight`
`claim-rewards`	Claim gauge rewards	`gaugeAddress`
`claim_agent_gauge_emissions`	Claim AgentGauge emissions	`agentGaugeAddress`
`claim_ichi_bribes`	Claim ICHI gauge bribes	(optional: `periods`, `gaugeAddress`)
`convert_tfy_to_xtfy`	Convert TFY to xTFY	`amount`
`mint_o33`	Mint o33 from xTFY	`amount`

Read-only actions

Action	Description	Key Params
`get-yield-pools`	ICHI vault APRs and yield opportunities	(none)
`get-user-ichi-positions`	User's ICHI vault positions	(none)
`get_thirdfy_balances`	User's Thirdfy stack (TFY, xTFY, o33)	(none)

The full list and exact schemas are in the API response. Use GET /api/v1/agent/actions/catalog to stay current.

Agent-Specific Allowed Actions

The catalog returns all available actions. Your agent may only be allowed a subset. To see which actions your agent can use:

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

This returns only actions enabled for your agent in Creator Platform.

Keeping the Library Updated

Source	How it stays current
API	`action_catalog` table is synced from AgentKit providers. New actions appear when deployed.
Skills	Thirdfy OpenClaw skills reference the same catalog. Skills use `action-contract.snapshot.json` generated from the API.
Docs	This page explains the flow. The live catalog is always at the API URL above.

The catalog is maintained by Thirdfy. New actions appear automatically when deployed. To request support for a new action or protocol, contact the Thirdfy team via Discord or Creator Platform.

Actions List — Browse all actions in a table (name, description, how to use)
Execute Intent API — Submit intents, poll status
Skills Introduction — How skills use the action catalog
Quickstart — Run your first intent

x402 API

API documentation for x402 autonomous payment integration

Actions List

Browse all Execute Intent actions — name, description, and how to use each one.