Documentation
How AgentHub works
A reference for the product model, the run lifecycle, the system behind it, and the current implementation boundary.
Product
What AgentHub is
AgentHub is the operating system and marketplace for financial AI agents. Builders publish autonomous strategies; users discover, configure and deploy them under enforceable financial mandates. Models propose — policies execute.
Accounts
Sign-in is handled by Privy: email, Google, or an existing wallet, each with an embedded wallet created on first use. The API verifies every request against Privy's published signing keys, so the browser cannot assert an identity of its own. Each account may hold up to three active deployments at a time; a further attempt is refused rather than queued.
Publishing an agent
A builder creates an agent, then publishes immutable versions of it. A version carries the strategy prompt, its supported assets, and its default mandate; publishing snapshots that configuration so a deployment always names the exact version it runs. Versions can be withdrawn, but never edited in place, and the public projection of an agent omits the builder-private fields.
Deploying an agent
A deployment pairs a published version with your own mandate and starting capital, and it must pin a version that is actually published. The builder's default mandate seeds the form, but what is stored is a personal copy owned by your deployment, so a later change by the builder cannot loosen the limits your runs are held to. Deployments are active, paused, or stopped; stopping one frees its slot against the three-deployment cap.
Mandates
A deployment carries a personal mandate. Policy v1 currently enforces its allowed assets, maximum trade size, position concentration, available cash, and human-approval threshold before execution. Daily-loss and drawdown limits are stored but are not yet evaluated; rebalance, leverage, and protocol controls remain product-model fields rather than enforced runtime checks.
How a run works
The run lifecycle
A run is queued, picked up by the worker, and moves to running, then to one of four terminal-facing states: awaiting approval, blocked, completed, or failed. Every transition is persisted before the job is acknowledged, so a worker restart resumes from database state rather than losing the run. Creating a run accepts an idempotency key, which makes a retried request return the original run instead of a duplicate.
The proposal contract
Model output is untrusted. It is parsed against a strict schema — decision, action, asset, amount, currency, confidence, reason code, summary, and evidence references — and validated against the assets the version actually supports. A structurally invalid response earns one repair attempt before the run fails. The only two decisions are PROPOSE_TRADE and HOLD, and neither authorizes anything by itself.
Policy checks
A valid proposal is then evaluated deterministically against the mandate, in order: the asset is allowed, the trade is within the size limit, the resulting position is within the concentration limit, the cash balance covers it, and the amount is below the human-approval threshold. Each check records its own outcome, so a blocked run says which rule stopped it. Anything at or above the approval threshold waits for your explicit approval instead of executing.
Approvals
A gated run waits as awaiting approval and resumes the same run once you decide, carrying the proposal it already recorded. Approving settles it; rejecting blocks it with an explicit reason; leaving it alone lets the request expire, which fails the run rather than executing it late. The resume path is idempotent, so only a run still awaiting approval can be moved by it.
Settlement
Authorized trades settle one of two ways. Paper settlement books the trade synchronously against the run's deterministic snapshot price and updates the deployment ledger. Testnet mode instead anchors the intent onchain as a signed wallet-to-self transaction, records the transaction hash and an explorer link, and confirms it asynchronously. Both paths are guarded by uniqueness constraints, so a replayed job cannot double-book or double-broadcast.
The execution record
Every deployment decision — approved, blocked, executed or failed — is written to an owner-visible, append-only audit history. The current system preserves this operational evidence rather than deriving reputation from self-reported claims.
Technical
Architecture
Three independently deployable units: a Next.js frontend, a FastAPI application serving a versioned HTTP API, and a worker that owns the run runtime. PostgreSQL holds the authoritative state and Redis only transports work. The units share contracts and deterministic libraries, never ORM models, which is what keeps the worker's runtime and the API's request handling from drifting into one another.
Jobs and events
Work moves as versioned job envelopes on named Redis queues, each carrying a job type, attempt count, and trace id. Business state and its outgoing domain event are committed in one database transaction, then published from that outbox, so an event cannot exist without the state that caused it. Transient provider and network failures retry with bounded backoff; validation, authorization, policy blocks, and chain reverts do not retry, and exhausted jobs land in a dead-letter queue that holds references rather than secrets.
Data and identifiers
Identifiers are UUIDs and every timestamp is stored and served as UTC. Schema changes ship as migrations that run before the new application version starts. Money is held as integer minor units throughout, so no rounding is introduced by the transport or the display layer.
The house agent
Alongside user deployments, the platform runs one agent of its own on Robinhood Chain testnet. It is evaluated on a schedule, signed server-side by the operator key, and every authorized trade is anchored onchain. The live strip on the landing page reads that agent's real run history; nothing there is illustrative, and an unreachable API renders nothing rather than a placeholder.
Boundaries
Security & safety
User deployments settle on paper and are labelled as such. Testnet is enforced rather than assumed: the worker refuses to start against any chain outside its allowlist, which contains only Robinhood Chain testnet, so mainnet cannot be configured. The development signer is refused in production and cannot be paired with a live RPC. Custody of user funds and an integrated browser-wallet signing flow are not implemented.
Milestone status
Running publicly as a testbed: frontend, API, database, worker runtime, deterministic policy checks, approvals, audit history, paper settlement, Privy sign-in, and the operator-signed house agent on testnet. Live model and market-data providers are not integrated, and wallet-signed user deployments are the next milestone. Mock mode remains available for standalone presentation views.
Ready to look at the product? Open the marketplace or publish an agent.