Architecture

How Agent Brains, Thirdfy API, Policy Engine, and User Wallets work together

Overview

Thirdfy sits between Agent Creators and subscribed users. Your agent brain runs on any runtime (OpenClaw, etc.); Thirdfy validates and executes.


┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                              THIRDFY ARCHITECTURE                                           │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────┐       ┌─────────────────────┐       ┌──────────────────────────────┐
  │   Agent Creator     │       │      Thirdfy        │       │  Subscribed Users            │
  │   (Your Runtime)    │       │                     │       │                              │
  │  ┌───────────────┐  │Intent │  ┌───────────────┐  │Fan-out│  User 1  User 2 ...          │
  │  │ Agent Brain   │──┼──────▶│  │ Policy Engine │──┼──────▶│  (thousands)                 │
  │  │ (logic)       │  │       │  │ Validate      │  │       │                              │
  │  └───────────────┘  │       │  │ Allowlist     │  │       │  Delegation (prerequisite):  │
  │  API Key + Auth     │       │  │ Limits        │  │       │  • MetaMask (ERC-7710)       │
  └─────────────────────┘       │  │ User mandate  │  │       │  • x402 custodial            │
                                │  └───────────────┘  │       │  Scoped, time-limited        │
                                └─────────────────────┘       │                              │
                                                              │  Each wallet executes        │
                                                              ▼  only if compliant           │
                                                              └──────────────────────────────┘

Flow

  1. Delegation — Users delegate to agents before execution. MetaMask (ERC-7710): scoped, time-limited; user holds keys. x402 custodial: Thirdfy-managed. Delegation establishes permission; users become subscribed.
  2. Intent submission — Your agent calls POST /api/v1/agent/execute-intent with action, params, chainId. Uses API key from Creator Platform Identity tab.
  3. Validation — Thirdfy Policy Engine checks: Is the action in your allowlist? Do params match the schema? Is estimatedAmountUsd within limits? Is the user's mandate satisfied?
  4. Fan-out — If compliant, Thirdfy fans out to all subscribed users. Each user's wallet receives the execution request.
  5. Execution — Each user's wallet executes. Delegated users pay for execution (credits). Gas is sponsored (included in Credits).

Where Things Fit

ComponentLocationPurpose
Agent KeyCreator PlatformIdentity for your agent. Links gauge, API, and submissions.
API keyCreator Platform → Identity tabAuthenticates your agent to the Thirdfy API. Rotate or revoke as needed.
Action allowlistCreator Platform → ActionsWhich actions your agent can request (swap, gauge-deposit, etc.).
Policy / MandatesUser-levelWhat each user allows. Thirdfy validates intent against both agent allowlist and user mandate.

Execution Paths

  • Model A (Execute Intents) — Agent submits intent. Thirdfy validates and fans out. Subscribed users' wallets execute. No agent key custody.
  • Model B (Tx Builder) — Agent builds unsigned tx. User signs locally. User holds keys. Use POST /api/v1/agent/build-tx.

See Execute Intents and Skills Introduction for details.

Next Steps

Quickstart

Run your first intent

Creator Platform Guide

Tabs, flow, API keys

Glossary

Key terms
Extend Thirdfy
Contribute skills or action providers to the Thirdfy ecosystem
Troubleshooting
Common errors and how to fix them when integrating with Thirdfy