Architecture

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

Overview

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


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

  ┌─────────────────────┐       ┌─────────────────────┐       ┌──────────────────────────────┐
  │   Agent Creator     │       │      Thirdfy        │       │  Delegated 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.
  2. Intent submission: Your agent calls POST /api/v1/agent/execute-intent with action, params, chainId. Uses an API key from email onboarding (CLI login email or MCP completeEmailOnboarding) or optionally 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 delegated users. Each user's wallet receives the execution request.
  5. Execution: Each user's wallet executes. Delegated users pay through USD execution balance or free requests.

Where Things Fit

ComponentLocationPurpose
Agent API keyEmail OTP (CLI/MCP) or Creator Platform IdentityAuthenticates catalog, preflight, and execute-intent calls
Agent profileCreator Platform (optional)Directory listing, skills package, production review
Action allowlistAgent policy / onboardingWhich actions your agent can request (swap, earn deposit, bridge, 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. Delegated 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