Actions Reference

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

Overview

The action catalog is the source of truth for what Thirdfy can execute. CLI (thirdfy-agent actions), MCP (getActionsCatalog, getProviderActions), and REST all read the same catalog.

Always current: Fetch GET /api/v1/agent/actions/catalog. This page explains the JSON shape. Actions List is the browsable table.

Execution: Use Agent CLI or MCP to run actions. You do not need to call POST /execute-intent from an agent host.

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`, `place-hyperliquid-perps-order`)
`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: Discovery flow

# Fetch catalog (no auth)
curl -s "https://api.thirdfy.com/api/v1/agent/actions/catalog" \
  | jq '.actions[] | {action, description, requiredParams}'

Then execute through your integration surface:

Surface	Next step
CLI	`thirdfy-agent preflight` → `thirdfy-agent run --action ...`
MCP	`getProviderActions` → `walletExecute` or `executeIntent`
Custom HTTP	Execute Intent API

Input Key Format

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

How to use the catalog

Discover — MCP getActionsCatalog / getProviderActions, CLI thirdfy-agent actions, or GET .../actions/catalog.
Match intent — Map user goal to an action and requiredParams.
Preflight — CLI preflight or MCP readiness tools before writes.
Execute — CLI run, MCP walletExecute / executeIntent / agentRun.

Use paramsSchema and supportsExecuteIntent / supportsBuildTx to validate before calling any write tool.

Example actions (integrations)

Action	Category	Key params
`swap`	Trading	`tokenIn`, `tokenOut`, `amountIn`
`get-best-trading-quote`	Trading	quote fields per catalog
`place-hyperliquid-perps-order`	Hyperliquid	per `getProviderActions { provider: "hyperliquid" }`
`deposit-earn-position`	Yield	vault/position fields per earn provider
`place-polymarket-order`	Prediction	market and size fields per catalog
`execute-bridge`	Bridge	route fields per Li.Fi hints

Read-only discovery

Action	Category	Key params
`get-earn-opportunities`	Yield	filters per provider
`get-hyperliquid-user-state`	Hyperliquid	wallet context
`get-polymarket-markets`	Prediction	search filters

Retired V1 protocol actions (TFY/xTFY/o33 conversions, gauge votes, ICHI vault ops) remain in the API for compatibility but are omitted from public docs examples. See Legacy V1.

The full integration catalog and exact schemas are in the API response or Actions List.

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.