Execute Intent API

Execute Intent API

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

Base URL

Endpoints

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.

Query parameters

Example

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 subscribed users.

Request body

Example: Swap

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)

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

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

{
  "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)

{
  "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

Example

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

Example

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..."
  }'

Integration Checklist

OpenClaw Trading Agent Example

Full flow for building an OpenClaw agent that executes trades via Thirdfy Execute Intent.

1. Prerequisites

• OpenClaw agent runtime
• Creator Platform account with registered agent and API key
• Thirdfy skills installed in your agent

2. Install Thirdfy Skills

Add the Thirdfy Intent API skill to your OpenClaw agent. In Creator Platform or your Skills panel, add:

https://thirdfy.com/skill.md

Or from GitHub: https://github.com/thirdfy/thirdfy-openclaw-skills

The skill provides the curl commands your agent will use via the exec tool.

3. Environment Variables

export THIRDFY_API_URL="https://api.thirdfy.com"        # or https://api-test.thirdfy.com for testnet
export THIRDFY_AGENT_API_KEY="your_api_key_from_creator_platform"

4. Flow: Agent → Thirdfy Execute Intent

┌─────────────────┐     GET /actions       ┌─────────────────┐
│  OpenClaw       │ ───────────────────►   │  Thirdfy API    │
│  Trading Agent  │                        │                 │
│                 │    POST /execute-intent│                 │
│                 │ ───────────────────►   │  Validates      │
│                 │                        │  Fans out to    │
│                 │     GET /status        │  subscribed     │
│                 │ ◄───────────────────   │  users          │
└─────────────────┘                        └─────────────────┘

5. Agent Logic (Pseudocode)

Your OpenClaw agent uses the exec tool to run curl. Example flow:

1. List allowed actions — Before executing, the agent calls GET /api/v1/agent/actions to see which actions (swap, vote, claim) it can request.
2. Submit intent — When the user asks to swap, the agent builds the JSON body and runs:
   curl -X POST "$THIRDFY_API_URL/api/v1/agent/execute-intent" \
     -H "Content-Type: application/json" \
     -d '{"agentApiKey":"'$THIRDFY_AGENT_API_KEY'","action":"swap","params":{...},"chainId":8453,...}'
   

3. Poll status — The agent polls GET /api/v1/agent/execute-intent/status?intentId=<id> until status is completed or failed.
4. Report results — Parse results[] (per-user txHash, success) and inform the user.

6. Model A vs Model B

For most trading agents, Model A (Execute Intent) is recommended — Thirdfy handles validation, policy, and fan-out.

7. Skills Reference

• Thirdfy Intent API Skill — Model A, fan-out
• Thirdfy Tx Builder Skill — Model B, local signing

Related

• llms.txt — Machine-readable map for AI agents. Read this first.
• Quickstart — Run your first intent with curl
• Execute Intents — Platform overview and flow
• Creator Platform — Register agents, get API keys
• Troubleshooting — Common errors and fixes