Execute Intent API

HTTP mirror for execute-intent, status, and build-tx. Prefer Agent CLI or MCP for agent execution.

Overview

Submit and track intents for registered agents. Thirdfy validates policy, then fans out to delegated users or executes on an agent wallet lane.

CLI and MCP equivalents

RESTMCPCLI
GET .../actions/cataloggetActionsCatalogthirdfy-agent actions catalog
GET .../actionsgetAgentActionsthirdfy-agent actions
POST .../execute-intentexecuteIntent, agentRunthirdfy-agent run
GET .../execute-intent/statusgetIntentStatusthirdfy-agent intent-status
POST .../build-txbuildTxthirdfy-agent build-tx

Hosted agents should not reimplement this table with raw curl unless they operate outside CLI and MCP.

Base URL

EnvironmentBase URL
Productionhttps://api.thirdfy.com
Testnethttps://api-test.thirdfy.com

Endpoints

GET /api/v1/agent/actions/catalog

Full public catalog (schema, params, provider families). No authentication.

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

See Actions Reference and Actions List.

GET /api/v1/agent/actions

Actions allowed for your agent key. Omit agentApiKey for the full list.

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 and fans out to delegated users.

FieldTypeRequiredDescription
agentApiKeystringYesAgent API key
actionstringYesCatalog action name
paramsobjectYesAction-specific parameters
chainIdnumberNoDefaults to 8453
estimatedAmountUsdnumberNoPolicy limit hint
idempotencyKeystringNoStrongly recommended for write retries

thirdfy-agent run generates an idempotency key when you omit --idempotency-key. Pass your own stable key for deterministic retries across workers.

Example

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,
    "idempotencyKey": "swap-2026-03-01-001"
  }'

Common rejection codes: ACTION_NOT_ALLOWED, INSUFFICIENT_CREDITS, DAILY_FREE_LIMIT_EXCEEDED, METAMASK_IDEMPOTENCY_KEY_REQUIRED.

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

Poll fan-out intent status until completed or failed.

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

Solo agent_wallet executes via MCP walletExecute or CLI do not use this poll path. Read txHash from the direct response instead.

POST /api/v1/agent/build-tx

Build an unsigned transaction for BYOW (self) lanes.

FieldTypeRequiredDescription
agentApiKeystringYesAgent API key
actionstringYesCatalog action
paramsobjectYesAction parameters
chainIdnumberYesChain ID
walletAddressstringNoSigner address when required

Delegation

Fan-out to delegated users requires an active Gator binding before execute-intent succeeds.

RESTPurpose
POST .../delegation/createBuild payload for owner signature
POST .../delegation/activatePersist signed delegation
GET .../delegation/checkStatus gate
GET .../delegation/verifyOn-chain verification

Prefer Delegation API (with MCP/CLI map) and Delegation and protection.

Related

API Reference
Action catalog, x402 payments, and HTTP contract mirrors. Agents should use CLI or MCP for execution.
Delegation API
HTTP mirror for Gator/ERC-7710 delegation. Prefer MCP delegation tools or Agent CLI delegation commands.