IDLE-AI — Architecture

IDLE-AI is a launchpad where anyone can create an AI agent and give it a tradable token. This repository documents that system as it was built: its three deployables, the contracts behind them, the decisions that shaped it, and where it is heading.

The problem

Launching an AI agent that people can actually own a piece of requires three unrelated things to work at once. It needs a runtime that can drive the agent — talk to language model providers, hold a conversation, post to social platforms. It needs contracts that mint a real asset for that agent and let people trade it. And it needs an interface that makes both approachable to someone who has done neither before, on a chain they may not have used, with a wallet that may not know that chain exists.

Most projects solve one of the three and stub the others. An agent framework with no asset gives you something to talk to but nothing to hold. A token launcher with no runtime gives you an asset whose "agent" is a description in a database. IDLE-AI builds all three, and the interesting parts of its architecture are the seams — where the AI layer meets the token layer, and what each one does and does not know about the other.

How it works

You describe an agent: a name, a ticker, an icon, links, and how it should behave. You pay for the launch in IDL, the platform's own token. A factory contract deploys a brand-new ERC-20 for your agent and sends you an allocation of it, sized by what you paid. Your agent appears in a public catalogue that is read straight from the chain — no database anywhere in the system. From there anyone can trade its token, or open a chat and talk to the agent itself.

System at a glance

flowchart TB
    creator["Creator<br/><i>launches an agent</i>"]
    trader["Trader<br/><i>buys and sells</i>"]

    subgraph boundary["IDLE-AI"]
        direction TB
        webapp["Web Application"]
        runtime["Agent Runtime<br/><i>adopted ZerePy</i>"]
        contracts["Smart Contracts"]
    end

    llm["LLM Providers<br/><i>OpenAI · Anthropic · others</i>"]
    social["Social Platforms<br/><i>X · Farcaster · Discord</i>"]
    chains["EVM Testnets<br/><i>Sepolia · EDU Chain · Sonic</i>"]
    ipfs["IPFS<br/><i>via Pinata</i>"]
    wallet["Wallet<br/><i>via WalletConnect</i>"]

    creator --> webapp
    trader --> webapp

    webapp -->|"signs transactions"| wallet
    webapp -->|"chat and load"| runtime
    webapp -->|"uploads icons"| ipfs
    webapp -->|"reads and writes"| contracts

    runtime -->|"completions"| llm
    runtime -->|"posts and reads"| social

    wallet -->|"broadcasts"| chains
    contracts -.->|"deployed on"| chains

Loading

The three components

Smart Contracts — five Solidity contracts compiled with 0.8.28 and deployed across four EVM testnets. IdleToken is the platform token IDL. FactoryToken is the launchpad and the registry: it takes payment, deploys an ERC20Token per agent, stores the agent's metadata on-chain, and holds the reserves that trades price against. Swap and TokenSwap are two further exchange mechanisms. Because the metadata lives in the contract, the factory is also the platform's database — the whole catalogue is one getAllTokens() call. → docs/03-components/smart-contracts.md

Agent Runtime — this is ZerePy, an MIT-licensed agent framework by the Blorm team, adopted by IDLE-AI largely as it stands and supplied with the platform's own agent configuration. It is a Poetry-managed Python service that optionally exposes FastAPI, and its value is its connection layer: one module per external integration, covering ten language model providers, four social platforms, and five chains, all behind a single abstract interface. What IDLE contributes here is configuration, not framework. → docs/03-components/agent-runtime.md

Web Application — a Next.js App Router application in TypeScript, using wagmi and RainbowKit. It is the only component that talks to both other two. Chain access happens in the browser, signed by the user's wallet; three server-side route handlers reach IPFS and the agent runtime, so no credential and no internal address ever reaches the client. → docs/03-components/web-app.md

The headline flow

Launching an agent is the path the whole platform exists to serve:

sequenceDiagram
    autonumber
    actor C as Creator
    participant WA as Web Application
    participant PN as Pinata / IPFS
    participant IT as IdleToken
    participant FT as FactoryToken
    participant NT as new ERC20Token

    C->>WA: describe the agent at /agents/create
    WA->>PN: POST /api/pinata (icon)
    PN-->>WA: iconURL

    C->>IT: approve(FactoryToken, paymentAmount)
    C->>FT: createTokenWithPayment(name, ticker, iconURL,<br/>description, Twitter, Website, Behavior, paymentAmount)
    FT->>IT: transferFrom(creator, factory, paymentAmount)
    FT->>NT: deploy ERC20Token(name, ticker,<br/>1_000_000_000e18, factory)
    FT->>FT: push TokenInfo, write tokenDetails
    FT->>C: transfer(amountOfTokens)
    FT->>FT: transfer(hardcoded dev address, amountOfTokens)
    FT-->>WA: TokenCreated event

Loading

Five more flows — browsing, chatting, trading, swapping, and switching networks — are in docs/04-flows.md.

Design decisions

Ten decisions are reconstructed as records in docs/adr/. Four of them explain most of the system. Adopting ZerePy rather than building a connector layer is why the platform has three deployables and why its own effort went into the token side (ADR 0001). Giving every agent a real, separately deployed ERC-20 rather than internal accounting is what makes owning a piece of an agent mean something outside the platform (ADR 0002). Charging for creation in IDL gives the platform token a use and ties the creator's allocation to what they paid (ADR 0003). And storing agent metadata on-chain in the factory is why there is no database in the architecture at all (ADR 0005).

Where this is heading

The most consequential next step is a sequence of two: rotate the deployer credential committed in the contract repository, then redeploy the factory with the developer allocation recipient as a configurable variable rather than a literal compiled into the bytecode. The first alone does not change what is deployed; the second is what closes it. Giving the factory a withdrawal path for the IDL it collects follows immediately, since that is what makes creation revenue usable.

Beyond those, two changes turn the platform from a demonstration into a service: giving the agent runtime a durable endpoint instead of a hardcoded tunnel hostname, and reconciling the contract interfaces the frontend carries with the contracts that actually exist. The full ten-item roadmap, ordered by leverage, is in docs/08-future-work.md.

Documentation map

Document	The question it answers
docs/01-context.md	Who uses this, what it depends on, where its boundary falls
docs/02-containers.md	What the three deployables are and how they talk
docs/03-components/smart-contracts.md	What each contract stores, does, and permits
docs/03-components/agent-runtime.md	What is ZerePy's, what is IDLE's, and what the runtime exposes
docs/03-components/web-app.md	Routes, chain configuration, contract bindings, components
docs/04-flows.md	What happens, step by step, for each thing a user can do
docs/05-data-model.md	What is stored, where it lives, and how the two halves relate
docs/06-security-model.md	Trust zones, access control, credential custody, value custody
docs/07-deployment.md	Which networks, which addresses, how it is built and run
docs/08-future-work.md	What comes next, in order of leverage
docs/adr/	Why the system is shaped the way it is

Source repositories

Repository	Role
AIAgent-IDLE	The Agent Runtime — adopted ZerePy plus IDLE's agent configuration
SmartContract-IDLE	The five Solidity contracts, Hardhat toolchain, tests, and deploy scripts
Frontend-IDLE	The Next.js web application, contract bindings, and API routes

About this repository

This repository documents the IDLE-AI system as built. It contains no application code, and it modifies none: the three repositories above are read-only inputs.

Every identifier here — contract, function, field, module, route, address — is quoted verbatim from those sources. Where documentation and source disagree, the source is right and this is a defect to be fixed.

tools/verify-docs.sh enforces that mechanically on every change. It scans for placeholder markers, checks code fence balance and Mermaid fence validity, resolves every internal link, verifies that no contract address appears that is not present in the source repositories, and fails the build if the credential described in docs/06-security-model.md is ever reproduced here.

bash tools/verify-docs.sh