A marketplace for agents on BNB Chain. Every agent is a cartoon pufferfish, and its puff level is not decoration: it is one real risk metric rendered as a shape. Every number on a page links to the transaction behind it, and where there is no record the page says so instead of filling the gap.
| Landing | hellofugu.xyz |
| Marketplace | app.hellofugu.xyz |
| API | api.hellofugu.xyz/api/health |
| Agent endpoint | agents.hellofugu.xyz/guardian/ |
| Demo video | Google Drive |
| Repo | github.com/Lexirieru/fugugent |
| X | @hellofuguai |
| Tracking (BNB Chain Phase 2) | api.hellofugu.xyz/api/tracking · docs/phase2/TRACKING.md |
Contracts on BscScan · Receipts · Run it locally · What is not built
Built for the BNB Chain hackathon "The Smart Money Era: Build the Era".
The honest headline: nine agents are listed, and exactly one of them has ever sent a transaction. That sentence is on the site, at the end of the demo video, and in
docs/STATUS.md, which is the document to read if you want to know what this project cannot do. Every link below opens a public explorer, so nothing here needs a terminal or an account to check.
Two problems, and the second one is the harder one.
A lending position does not get liquidated because the borrower is broke. It gets liquidated because the borrower was asleep. The collateral fell 13% overnight, the health factor slid from 1.8 to 0.99, and the liquidation bot — which never sleeps — took its bonus out of someone who had the money to repay and simply was not at the screen. The fix is boring and mechanical: watch the position, and when it crosses a threshold, pay part of the debt back. Nobody wants to be the human doing that at 3am, and handing a bot your private key to do it for you is a worse trade than the liquidation.
And in the agent market, nobody can check anything. On 26 February 2026, Giza wound down
ARMA and Pulse — a DeFi agent product that had advertised >$16M TVL, $1.3B in "agentic volume",
15% APY, and a backtest claiming "2x yield enhancement". It was replaced by a successor showing
large assets-under-agent figures with no third-party verification, while an independent on-chain
measurement in June 2026 found agent positions near zero. The dashboard told one story and the
chain told another, and no visitor to that dashboard had any way to tell which was true.
(Sources and the full landscape survey: docs/research/05-competitive-landscape.md.)
That is the bar HelloFugu sets for itself: every number a card shows must be reachable by a
call anyone can make. If we cannot link it to a transaction, an event log, or an eth_call,
it does not go on the card.
| 🐟 | Agents are pufferfish | Four cartoon fugu, one per DeFi category. Their body shape is bound to a risk number, not to a mood. |
| 🎈 | Bloat = risk load | Five levels, driven by the same thresholds the decision engine uses. Level 3 is the first level that spends money, and the ring pattern changes from solid to dashed to say so without relying on color. |
| 🔑 | Scoped session keys | An agent never holds your keys. It holds an Altana session key restricted to a contract and a function selector, with a daily spend cap and an expiry. Anything else is rejected by the account contract. |
| 🧮 | Deterministic strategies | Every financial decision is bigint arithmetic with a written justification and a backtest. No LLM sits on the path between a price and a transaction. |
| 🔍 | On-chain marketplace | Listing, hiring, streaming payment, and reviews are four upgradeable contracts on BSC testnet. Reviews are gated on the agent actually having been paid. |
| ⏹️ | Hire, cap, cancel | A hire is a deposit held in escrow and paid out by the second. The price and the deposit are the spend cap; cancelling stops the payout and refunds the rest in the same transaction. |
| 🗂️ | My agents | /me shows everything one wallet did here: what is running now with a live countdown, past hires, ratings, and the agents it owns. Each row is read from the chain. |
| 📊 | Real agent data | The catalogue is read straight from the canonical ERC-8004 IdentityRegistry on chain 97, no seed rows, no hardcoded list. Our twenty agents are ERC-8004 ids 2480–2488 and 2507–2517. |
Network: BSC testnet, chainId 97 · RPC https://data-seed-prebsc-1-s1.bnbchain.org:8545
· Explorer testnet.bscscan.com
All five are UUPS upgradeable and every implementation is verified on BscScan, so the Read as Proxy and Write as Proxy tabs work in your browser.
| Contract | What it holds | Proxy (use this address) | Verified implementation |
|---|---|---|---|
| FuguRegistry | The agent catalog: listing, category, price, owner vs. agent wallet, and the ERC-8004 id each listing is bound to (only that id's owner can list it) | 0xb2f36070E6eae3353E8e755172B477DF213ae248 |
0xC4c9668c13380800f9F0a54e9ddb4C3d35cDa2Da |
| FuguSubscription | Escrow + time-streamed payment from renter to agent | 0xfdb083371f44Cf53181350389D3217e51B431776 |
0xFbDe18E19fC5e7ebC9404c05B081945DEF3Ce5c7 |
| FuguReputation | Reviews, gated on the agent having actually been paid | 0x279B31B00F64C0ce85BCe2Bd7e377CdcAE58d400 |
0x30c92ffadad24ca079227a92a33b78683d36fde6 |
| FuguPriceOracle | Chainlink-backed USD→token quoting, 8-decimal USD base | 0xB5f72a0ab0bA971c8C4F69D4A075cB7fd7859e65 |
0x864f888330821b6025b2FE670f30E01Ee8776449 |
| FuguAuditEscrow | Two-sided escrow for the audited-skill marketplace: the developer's fee and the auditor's bond, held together | 0x0354d2a4be40f118e4d1301915ee2ff54eec8a52 |
0xf7a0e340455af3c476564d7af283d9be4d2cfabb |
You do not have to trust the implementation column. Open any proxy above on BscScan and use the Contract → Read as Proxy tab: BscScan resolves the implementation from the ERC-1967 slot itself and shows you which contract the calls actually land in.
These exist so a rescue agent can be tested against a position that really moves. The
lending pool is ours, written by us, ABI-compatible with Aave v3's getUserAccountData.
The positions and the transactions are real; the pool is not a real lending market.
| Contract | Address |
|---|---|
| MockLendingPool | 0xb3e1F06Ac529aded2aA20aA38F4C0b4AD317e5F5 |
| MockTokenUSD (mUSD, 18 decimals) | 0x932E82632E80b06318ca969e33F99A54F1a04b10 |
| MockTokenBNB (mBNB, 18 decimals) | 0xF380E8B6803aD065EF0567dd20C894a55050737c |
| MockPriceFeed mBNB (8 decimals) | 0x0aA42416bAccdb2fd4768B61111DeB7F7D212F9B |
| MockPriceFeed mUSD (8 decimals) | 0x5B0770513b6CD76Bf225462F3ec42783E8Da69A1 |
| Role | Address |
|---|---|
| Deployer / EOA | 0x56A2950ddE6B1040d1DCC4b4C4Fc314Bd56eFB0E |
| Fugu Guardian — Altana wallet | 0xbdc69c2d7FE7337C86d6Ab63E1B3A89D67e5A0c0 |
| Fugu Rebalancer — Altana wallet | 0xb8f155D1278f0437b9De7c63911f2C0EDa485941 |
| Fugu Grid — Altana wallet | 0x2AA59d5cf540c8f1b1CE4C667C2e745475d4EAd9 |
| Fugu Yield — Altana wallet | 0x15dE73F47Ca58a11A6Ef9dB24dfDc6F096b0a866 |
| Altana Keystore (session key registry) | 0x6b8361C29d05D498b1a12B54A37310f94171E94A |
| Altana Controller | 0xb530D1971f5453F3359518343F05D0AedFfF7e12 |
Three claims carry the project. Each one links to a transaction you can open.
| Claim | An agent read a position, decided on its own how much to repay, sent the repayment, and the health factor rose from 1.14 to 1.50. |
| Repay tx | 0x619cfbe351703913ebafd0e76db86af0f90953bbff33335d78d8dbf1e41e08cc — status 1, block 129,852,222 |
| Price drop that created the danger | 0x19c09c5123c702d30bbb5532680895f4ccf717376976033e066a8cda1aa88ab6 — block 129,852,205 |
| Price restored afterwards | 0x82cc9086bd03dbd7fd73dcc47884e4f757220d317dae3a86716790bca89e6801 — block 129,852,279 |
| Amount | $4.03 repaid — 403063169 in 8-decimal USD base. The on-chain debt decrease was 403063169. Difference: 0 units. |
| Who picked the amount | repayToReachTarget(pos, warn) in decide.ts — the exact amount that lands the health factor back on the 1.50 threshold. It landed on 1500000000000000000. |
| Honest caveat | The lending pool is ours (see Security & limitations). What is proven here is the chain read → decide → execute → HF rose, not that the Guardian runs on Aave. |
An earlier run of the same code path — kept in the evidence log as history, superseded by the
one above — is 0xd7acda4cc6505da3ea9b89911b7fa8a884147f0e67e11e6fb9cc8d99d638d06e
(block 129,849,537, $5.25 repaid, same 1.14 → 1.50). We replaced it as the binding receipt because
the state store changed between runs, and evidence for code that is no longer running is not
evidence. Full history: docs/e2e/2026-09-08-e2e-testnet.md.
| Claim | The repayment was signed by an Altana session key restricted to two functions — not by the deployer EOA. |
| Proof in the receipt | The Repay event's user field is 0xbdc69c2d… — the Guardian's Altana wallet — and the transaction's from is an Altana relay (0x09f6ac70…), not 0x56A2950d…. Repay.user is msg.sender at the pool. |
| The session key is registered on chain | keyHash 0x7a467115cdf6d03f85f0f059733843b43cbe291d9f4489e3bf27d45e5148b377, grant tx 0x15e67a21… |
| Check it yourself, no account needed | see below, it returns true |
Open the Altana Keystore's Read Contract tab,
find isValidKey, and paste these two values:
| Field | Value |
|---|---|
account |
0xbdc69c2d7FE7337C86d6Ab63E1B3A89D67e5A0c0 |
keyHash |
0x1a64e047eee99ee93787c6418709a907c1501693ae24ccaba864ff7aaec79b2c |
It answers true. That is the current key: the one that signed the repay above
(0x7a467115cd…) expired on 8 Oct 2026 and now answers false, and the session was
renewed on 11 Oct 2026 with the same two-entry allowlist and the same caps
(grant tx), valid until 9 Nov 2026. The permission is registered on the chain, not asserted by us, and the
marketplace shows the same call's result on
Fugu Guardian's page.
The whole session allowlist is two entries, each binding a contract and a selector:
| Contract | Selector allowed |
|---|---|
MockLendingPool 0xb3e1F06A… |
repay(address,uint256) |
mUSD 0x932E8263… |
approve(address,uint256) |
Daily spend cap 0.02 tBNB + 100 mUSD. Expiry 8 October 2026. Nothing else.
This is the one that matters. Anyone can write an if statement that refuses to send a
transaction. We wanted the refusal to come from somewhere we do not control.
| Attempt through the same session | Why it is outside the boundary | Result |
|---|---|---|
mUSD.transfer(0x56A2950d…, 1 wei) |
the contract is allowlisted for approve; the transfer selector is not |
rejected |
mBNB.approve(pool, 1 wei) |
the approve selector is allowlisted for mUSD; the mBNB contract is not |
rejected |
Both fail with the Altana account contract's custom error:
Reason: UnauthorizedCall
Details: UnauthorizedCall({ keyHash: 0x80c191a2…, target: 0x932e82632e80b06318ca969e33f99a54f1a04b10, data: 0xa9059cbb… })
Zero gas burned, balances unmoved. Reviewing this claim, we grepped the entire node_modules
tree for the string UnauthorizedCall — it is not there. The rejection came from the chain.
The test helper assertSessionDenial is deliberately strict about this: a thrown exception is
not proof, because a dead relay, an HTTP 502, or a nonce race all throw too. The error must
contain UnauthorizedCall and name the contract we tried to call. Pointing the relay at a
dead endpoint makes the probe exit 1 instead of printing a checkmark.
⚠️ What this does not prove: the rejection leaves no on-chain trace. It happens while the relay simulates the userOp against the account contract, so there is no block a judge can open. The correct sentence is "rejected by the Altana account validator during relay simulation", not "a reverted transaction exists on chain".
Run earlier, still valid — the full rent-and-review cycle for 0.0015 tBNB total.
| Step | Result read back from chain | Tx |
|---|---|---|
| List an agent (Health Factor, $0.10 / 120s) | listingCount = 1 |
0x590d2f13… |
| Rent it and pay in tBNB | escrow funded, subCount = 1 |
0x15810ba2… |
| Agent claims its accrued share | 17668387054596 wei left in escrow |
0xe0fd365d… |
| Write a 5-star review | reviewCount = 1, averageScoreX100 = 500 |
0xf7bd2369… |
The anti-sybil gate was checked on both sides of the money: hasSubscribed was false before
the agent was paid and true after. That is the whole content of "only people who actually paid
can review", and it flips at the moment money moves, not at the moment someone subscribes. A
second review from the same wallet reverts.
frontend/e2e/my-agents-live.mjs drives https://app.hellofugu.xyz with Playwright and a
real testnet wallet (the key signs inside the script and is never typed into a page). Last
run, 27 Sep 2026: connect on /me → hire Fugu Guardian from
its page → /me lists sub #6 under "Running
now" with a countdown ticking 19:55 → 19:53 → cancel from /me → 0.001271 tBNB
refunded, and getSub(6).cancelled == true on
FuguSubscription.
The wallet was asked to sign exactly two things: subscribe and cancel.
flowchart LR
U([👤 User]) -->|browses| FE[Marketplace<br/>Next.js 16]
FE -->|GET /api/agents| BE[BFF<br/>Hono]
subgraph SRC[Catalog sources · tiered fallback, no seed]
direction TB
T1[["① ERC-8004 IdentityRegistry<br/>state sweep via Multicall3"]]
T2[["② Postgres cache<br/>last good sweep"]]
T3[["③ On-chain<br/>FuguRegistry"]]
T1 -.->|RPC down| T2 -.->|cold| T3
end
BE --> SRC
BE -->|classify| CAT[9 categories<br/>REBALANCING … TREASURY]
U -->|rent · pay tBNB| SUB[FuguSubscription<br/>escrow + stream]
SUB --> REG[FuguRegistry]
SUB -->|gate| REP[FuguReputation]
U -->|grants scoped session key| KS[Altana Keystore<br/>contract + selector + cap + expiry]
subgraph AG[🐡 Fugu Guardian]
direction TB
READ[read position<br/>eth_call] --> DEC{{"decide()<br/>bigint arithmetic"}}
DEC --> EXE[executeDecision]
end
KS --> AG
AG -->|approve + repay<br/>one atomic userOp| POOL[(Lending pool)]
POOL -->|new health factor| BLOAT[🎈 puff level 1-5]
BLOAT --> FE
DEC -.->|after the fact,<br/>off the critical path| LLM[dGrid<br/>plain-language explanation]
LLM -.-> FE
classDef user fill:#0072B2,stroke:#05121A,stroke-width:2px,color:#fff
classDef app fill:#56B4E9,stroke:#05121A,stroke-width:2px,color:#05121A
classDef chain fill:#F0B90B,stroke:#05121A,stroke-width:2px,color:#05121A
classDef agent fill:#009E73,stroke:#05121A,stroke-width:2px,color:#fff
classDef llm fill:#CC79A7,stroke:#05121A,stroke-width:2px,color:#fff,stroke-dasharray: 5 3
classDef risk fill:#E69F00,stroke:#05121A,stroke-width:2px,color:#05121A
class U user
class FE,BE,CAT,T2 app
class REG,SUB,REP,KS,POOL,T1,T3 chain
class READ,DEC,EXE agent
class LLM llm
class BLOAT risk
sequenceDiagram
autonumber
participant L as Guardian loop
participant R as Chain reader
participant D as decide() · pure bigint
participant X as executeDecision
participant S as Altana session key
participant RL as Altana relay
participant A as Altana account contract
participant P as MockLendingPool
participant G as dGrid (LLM)
participant UI as Marketplace UI
L->>R: eth_call getUserAccountData(wallet)
R-->>L: collateral $150.00 · debt $17.27 · LT 7500bps
L->>D: computeHealthFactor(position)
Note over D: HF = collateral × ltBps × 1e18<br/>÷ (10000 × debt)
D-->>L: HF = 1.14 → zone PARTIAL_REPAY
L->>D: repayToReachTarget(pos, warn=1.50)
D-->>L: repay $4.03 (403063169 in USD-8)
L->>X: execute(PARTIAL_REPAY, 403063169)
Note over X: writes pendingRepay to disk<br/>BEFORE the tx leaves
X->>S: build userOp [approve, repay]
S->>RL: signed userOp
RL->>A: simulate against permissions
A-->>RL: both calls inside allowlist ✓
RL->>P: approve(pool, 4.03) + repay(mUSD, 4.03)
P-->>RL: Repay(user=0xbdc69c2d…, 4030631690000000000)
RL-->>X: tx 0x619cfbe3… status 1
X->>R: re-read, pinned to the repay block
R-->>X: debt $17.27 → $13.24 · HF = 1.50
Note over X: assert on-chain Δdebt == claimed amount<br/>tolerance 2 units · actual 0
X-->>UI: puff level 4 → 2
X->>G: explainDecision(facts) %% only now
G-->>UI: plain-language explanation
rect rgb(255, 235, 235)
Note over S,A: Negative control, same session:<br/>mUSD.transfer(...) → UnauthorizedCall, 0 gas
end
Note the ordering: explainDecision is called after the repayment is already broadcast. The
full cycle took 15.1 seconds including the dGrid call — which is only possible because the money
never waited for the model.
This is rule number one and nothing in the codebase is allowed to break it. Every number that moves money is deterministic bigint arithmetic with a written justification and a backtest. dGrid (
openai/gpt-5.6-luna) has been measured between 8 and 46 seconds per call — it is used for asynchronous explanation and for a research agent, and never on the critical path. If the model is down, slow, or hallucinating, the position is still defended correctly.
Read the last column before anything else. Exactly one of the nine has ever sent a transaction. The other eight are listed, priced and hireable, and hiring one holds your payment and starts nothing that runs on its own.
| Agent | Category | State today |
|---|---|---|
| 🛡️ Fugu Guardian | HEALTH_FACTOR |
decision engine, execution and a monitoring loop. The only one proven on chain, through a scoped session key |
| ⚖️ Fugu Rebalancer | REBALANCING |
decision engine and backtest. Cannot act |
| 📐 Fugu Grid | GRID |
decision engine and backtest. Cannot act |
| 🌾 Fugu Yield | YIELD |
decision engine and backtest. Cannot act |
| 🤝 Fugu Broker | HIRING |
picks and prices a rental. Wallet holds nothing, no session granted |
| 🔁 Fugu Trader | COMMERCE |
both sides of a per-call purchase, signature checked end to end in tests. Nothing settled |
| 🎛️ Fugu Pilot | AUTONOMOUS |
knows which venues actually exist on this testnet, and refuses the ones that do not. Nothing sent |
| ⏱️ Fugu Meter | STREAMING |
counts usage and pays without per-payment approval. b402 not touched yet |
| 🗓️ Fugu Steward | TREASURY |
recurring payments, and scope separation between agents on one wallet |
Agents 10–20 (ERC-8004 ids 2507–2517, registered 27 Sep 2026, every tx in
contracts/deployments/agents-10-20.json):
| Agent | Category | State today |
|---|---|---|
| Fugu Guardian Early | HEALTH_FACTOR |
Guardian's code with repay at 1.40 instead of 1.20. Has sent nothing |
| Fugu Rebalancer Wide · Fugu Rebalancer Stable | REBALANCING |
Rebalancer's code with a wider band / a stablecoin-only mix. Have sent nothing |
| Fugu Grid Wide · Fugu Grid Tight | GRID |
Grid's code with fewer, bigger / more, smaller steps. Have sent nothing |
| Fugu Yield Patient | YIELD |
Yield's code for a longer stay. Has sent nothing |
| Fugu Watch | HEALTH_FACTOR |
Runs. Reads a loan's health factor in Guardian's bands: /api/run/watch |
| Fugu Tally | TREASURY |
Runs. What a wallet spent hiring here: /api/run/tally |
| Fugu Scout | HIRING |
Runs. Who is on offer in a category, from ERC-8004: /api/run/scout |
| Fugu Keycheck | AUTONOMOUS |
Runs. Is a session key still valid: /api/run/keycheck |
| Fugu Quote | COMMERCE |
Runs. Dollars to tBNB at the oracle price: /api/run/quote |
The five read-only agents sign nothing and move no money; that is the whole of what they do.
None of these are magic numbers. Each has a written reason in the source, and each is the reason the agent refuses to act more often than it acts.
Fugu Rebalancer — a 50 bps cost gate on turnover. Portfolio rebalancing is worth a few
hundred bps per year; paying more than 50 bps in a single rebalance means the trade is eating
the thing it was supposed to earn. The interesting part is minEconomicTurnoverBase(): instead
of guessing a minimum trade size, it derives one from gas cost and the cost budget —
T ≥ gas × 10000 / (M − r) — and a configuration where no turnover can ever clear the bar fails
loudly at the entrance instead of silently never trading.
Fugu Grid — line spacing must be at least 2× the round-trip cost. A grid whose step is narrower than the cost of one buy-and-sell pair looks busy and grinds the capital down. The constraint is expressed against gas-per-lot, so it tightens automatically when the lot gets small.
Fugu Yield — breakEvenSpreadBps = ceil(cost × 10000 × 365 / (principal × days)), then × 2.00.
The migration cost is paid once; the yield spread is earned per day. That asymmetry is brutal at
small size: moving $10,000 needs a 390 bps spread to break even, moving $200 needs
1,582 bps. The 2.00× safety multiple on top is a product decision, and the source says so
rather than pretending it was derived.
Two of our own backtests proved the person who wrote the strategy wrong. We kept the results and named the tests after it.
| Test | What it found |
|---|---|
KEJUJURAN: pada ayunan besar di portofolio besar, 'rebalance selalu' justru unggul — pita ada ongkosnyaai/fugurebalancer/…/__tests__/backtest.test.ts |
On large swings in a large portfolio, always-rebalance beats the deviation band. The band is not free. |
KEJUJURAN: pada tren naik, beli-lalu-diamkan mengalahkan grid — grid menjual kenaikannyaai/fugugrid/…/__tests__/backtest.test.ts |
In a directional uptrend, buy-and-hold beats the grid. The grid sells the rally. |
(kejujuran is Indonesian for "honesty".) A backtest suite that only ever confirms its author
is not a backtest suite. These two run green in CI-less pnpm test alongside everything else,
and they are the reason we believe the numbers the others produce.
Five levels — not four, not seven. Five because that is exactly enough to cover the Guardian's
four decision thresholds (WARN, PARTIAL_REPAY, DELEVERAGE, EMERGENCY) plus one state
meaning "nothing to do".
Each level differs on six channels at once, because each channel survives a different failure: body width survives 16px and blur; spikes survive in silhouette; the face survives at ≥64px and carries the emotion; the ring pattern survives greyscale; the ring colour is fast for most readers and is never the only signal; and the numeric text chip is the one unambiguous channel, required on every card and detail page.
| Level | Name | Ring | Colour | Meaning |
|---|---|---|---|---|
| 1 | Calm | thin, solid, 40% arc | Reef Green #009E73 |
Nothing to do. The agent is alive and watching. |
| 2 | Watchful | solid, full, one notch | Shoal Yellow #F0E442 |
First threshold touched. Told you; spent nothing. Must not feel like an alarm. |
| 3 | Strained | dashed, full | Tide Amber #E69F00 |
First level with a financial consequence — the agent is about to spend money. The solid→dashed change says so without colour. |
| 4 | Critical | — | — | see docs/brand/puff-levels.md |
| 5 | Emergency | — | — | see docs/brand/puff-levels.md |
Absolute rule: the agent's body colour never changes with puff level. Only the body shape and the ring change. A Guardian in an emergency is still cobalt; it is just round, spiked, and ringed.
The thresholds come from one source — ai/fuguguardian/app/agent/src/strategy/types.ts
(DEFAULT_THRESHOLDS), and the backend ships bloatLevel: 1|2|3|4|5 derived from it. If the
UI number and the engine number ever diverge, we have reproduced exactly the failure that killed
ARMA: a dashboard telling a different story from the chain.
The character art is hand-written parametric SVG generated by docs/brand/generate-svg.py
from the same geometry numbers as the spec — not output from an image model. See
Security & limitations.
| Threshold | Value | Meaning |
|---|---|---|
warn |
1_500_000_000_000_000_000n = 1.50 |
notify; also the repayment target |
partialRepay |
1_200_000_000_000_000_000n = 1.20 |
repay part of the debt |
deleverage |
1_100_000_000_000_000_000n = 1.10 |
reduce the position |
# read them straight out of the source, not out of this README
sed -n '49,53p' ai/fuguguardian/app/agent/src/strategy/types.tsHF = collateral × ltBps × 1e18 / (10000 × debt)
dropToLiq = 10000 − ceilDiv(10000 × 1e18, HF)
repay = debt − collateral × ltBps × 1e18 / (10000 × target)
dropToLiq is the number a user actually cares about: how far can the collateral fall before
this gets liquidated. At HF 1.14 that was 13.0%.
| Convention | Value | Why it matters |
|---|---|---|
| Token decimals on BSC | 18 for everything, USDT included | not 6. Assuming 6 makes an agent pay one ten-thousandth of what it prints. |
| USD base | 8 decimals (12345678 = $0.12) |
never rendered raw |
| Health factor base | 1e18 | |
| Chain | chainId 97 only | |
| bigint over the wire | serialised as strings | a 30-digit value passed through Number corrupts: …901234567890 → …877719597056. Tested. |
You do not need a terminal for any of this. Every contract below is a verified proxy, so BscScan's Contract → Read as Proxy tab lets you call these functions in the browser and see the answer come back from the chain.
| What to read | Where | What it answers |
|---|---|---|
listingCount() |
FuguRegistry | how many agents are listed. 20 today |
countByCategory(uint8) |
same | how many in one category. 3 is Health factor |
subCount() |
FuguSubscription | how many rentals have been paid for |
getSub(uint256) |
same | one rental: who paid, how much is in escrow, how much has been claimed |
reviewCount(uint256) |
FuguReputation | reviews on a listing. Only a payer can leave one |
priceUsd8(address) |
FuguPriceOracle | the live BNB price the hire panel quotes, in 8-decimal USD |
The Category enum, in the order the contract stores it
(contracts/src/types/FuguTypes.sol):
0 REBALANCING · 1 GRID · 2 YIELD · 3 HEALTH_FACTOR · 4 HIRING · 5 COMMERCE ·
6 AUTONOMOUS · 7 STREAMING · 8 TREASURY
Per wallet, without BscScan: the tracking API reads the same contracts through Multicall3 and stamps every answer with the block it read.
curl -s "https://api.hellofugu.xyz/api/tracking/hires?wallet=0x…" # hires, with category
curl -s "https://api.hellofugu.xyz/api/tracking/agents?owner=0x…" # listings + ERC-8004 ids
curl -s "https://api.hellofugu.xyz/api/tracking/reviews?wallet=0x…" # ratingsThe marketplace reads exactly these functions and shows you the same numbers, so if a page and the chain ever disagree, the chain is right and the page has a bug.
Nothing here requires a deployment, an account, or a key. It requires Docker, Foundry, and Node.
git clone --recurse-submodules https://github.com/Lexirieru/fugugent
cd fugugentcontracts/lib uses git submodules for forge-std and both OpenZeppelin repos. If you already
cloned without them: git submodule update --init --recursive.
cd contracts && forge testFoundry 1.7.1, Solidity 0.8.30, OpenZeppelin 5.7.0. UUPS with ERC-7201 namespaced storage.
Each agent is its own pnpm workspace; install at the agent root, test in app/agent.
for a in fuguguardian fugurebalancer fugugrid fuguyield; do
( cd "ai/$a" && pnpm install && cd app/agent && pnpm test )
done
# fuguguardian 249 · fugurebalancer 88 · fugugrid 99 · fuguyield 93The two KEJUJURAN backtests are in there. Run them and watch our own strategies lose.
docker compose up -d --buildThree containers — fugugent-postgres, fugugent-redis, fugugent-api — and the API waits for
the other two to report healthy. Host ports for Postgres and Redis are deliberately shifted to
55432 and 56379 so they cannot collide with a Postgres you already run on 5432. The API
listens on 8787.
curl -s localhost:8787/api/health | jq
curl -s localhost:8787/api/categories | jq
curl -s 'localhost:8787/api/agents?category=GRID&limit=5' | jq
curl -s localhost:8787/api/agents/97:2480 | jq/api/categories answers from the ERC-8004 IdentityRegistry itself (source: "registry"):
the backend sweeps every id by state through Multicall3, pinned to one block, because no free
BSC testnet RPC serves historical eth_getLogs. Those are our classifications of agents that
actually exist on chain. There is no seed tier in the running service (seed: null in
backend/src/index.ts), so an empty catalogue is reported as empty, never padded.
# strict health: 200 while everything is up
curl -s -o /dev/null -w '%{http_code}\n' 'localhost:8787/api/health?strict=1' # 200
docker compose stop postgres
curl -s -o /dev/null -w '%{http_code}\n' 'localhost:8787/api/health?strict=1' # 503
curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' localhost:8787/api/agents # 200, ~0.57s
docker compose start postgres
curl -s -o /dev/null -w '%{http_code}\n' 'localhost:8787/api/health?strict=1' # 200 againTwo things this shows. First, ?strict=1 tells the truth: it returned 503 when Postgres was
down and, separately, when an upstream fell over on its own. Second, the catalog still answers in 0.57s with the database gone, down
from 31s before the timeouts were tuned. Degraded, fast, and labelled as degraded.
The fallback was proven by blocking DNS, not by flipping a config flag: tier 1 the ERC-8004
registry → tier 2 Postgres cache → tier 3 on-chain FuguRegistry. Each RPC read also falls
back across public endpoints (bnbchain seed node → publicnode → sentio) before a tier is
declared down. 8004scan is no longer a tier; it is only where a registration tx hash is
looked up, and the page shows that hash only after its receipt proves Registered(agentId).
NEXT_PUBLIC_API_BASE_URL=http://localhost:8787 bun --cwd frontend devBuilt this way, the page renders the same ERC-8004 agents /api/agents returns, and
/agent/97:2480 is Fugu Guardian. Stop Postgres or cut the RPC and the page relabels itself,
on its own, to something like:
Served from our cache · 9s old · not confirmed fresh
That sentence is the entire product thesis in one line of UI.
Every address and every transaction hash in this document is a link to testnet.bscscan.com. Open one and you are reading the chain, not our copy of it. For the contracts, the Contract → Read as Proxy tab calls the functions live in your browser: no terminal, no node, no account.
An agent that installs a poisoned skill drains its own wallet. That is not hypothetical: CVE-2025-54136 is tool poisoning and CVE-2025-6514 is supply-chain remote code execution, both in the same class of tooling these agents run on.
The usual answer is a badge. A badge is worth nothing, because nothing happens to whoever issued it when they are wrong.
So the auditor puts money on their verdict. FuguAuditEscrow holds two sides at once: the
skill developer locks the audit fee, the auditor locks an honesty bond, and the pot settles one
of three ways.
| Outcome | Who may trigger it | Where the money goes |
|---|---|---|
| Clean audit | the developer, or the arbiter | released to the auditor |
| Verdict proven wrong | the arbiter | slashed to whoever proved it |
| Still half funded | either side | cancelled back to both |
Who may move money is the part that matters. The auditor can never release to itself: a payee that can pay itself is not an escrow. The developer or an arbiter can release, so an auditor's bond cannot be held hostage by a developer who simply goes quiet.
Seven verdict states are read and never quietly promoted. verified is accepted only when the
status is also PASSED, and a status we do not recognise reads as INCONCLUSIVE rather than as
a pass. Each state carries four separate signals: a unique phrase, a unique glyph, a badge
texture, and a full sentence about whether to install it. That is so the difference survives a
grayscale screenshot, not only a colour one.
Live at app.hellofugu.xyz/skills and app.hellofugu.xyz/auditors.
Honest limit. The records on those pages are labelled examples, every one of them, and the escrow has never held a real fee. What is real is the contract, its tests, and the fact that the money paths were written before the marketing was.
We would rather you read this section than find it out yourself. Everything below is a real gap, stated plainly.
On the agents
- The agent runtime entrypoints (
dualMain.ts,mcpMain.ts,tools.ts) do not yet importsrc/strategy/. What actually runs the full chain today is the composition rootcreateGuardian()and the E2E scripts. The strategy is real and tested; the long-running daemon is not yet the thing calling it. - Rebalancer, Grid, and Yield are not wired to on-chain execution. They have decision engines and backtests. They have wallets and registered sessions. They have not sent a transaction.
- A hire can be revoked from the UI; the agent's session key cannot yet. Cancelling a hire
(on the agent's page or on
/me) stops the payout and refunds the unspent deposit on chain. What a renter cannot do from the UI is revoke the Altana session key the agent itself runs on: that isbag wallet session revokeby the operator. Tying a hire to a renter-scoped session key is the next piece of work. - Every rating on chain today comes from a team wallet. Listing 1 (Guardian) has one review,
left by the deployer, which also owns all nine listings.
FuguReputationgates reviews on payment but does not stop an owner reviewing their own listing. The team wallets are listed indocs/phase2/TRACKING.mdso they can be excluded.
On the session key model
- Altana permissions do not bind argument values — only contract + selector. The Guardian's
session is therefore technically permitted to call
mUSD.approve(anyone, anything). What actually holds it back: the per-token spend cap on the session, our own code only ever building anapprovefor the pool (which is worthless the moment the process is compromised), and the Porto guarded executor zeroing the allowance at the end of the userOp — third-party behaviour we observed empirically, not a guarantee our contracts make. Real argument binding needs an intermediary contract. - The rejection of an out-of-allowlist call leaves no on-chain trace. It happens during relay
simulation. A third party can check three things — the error string is the account contract's
custom error and appears nowhere in
node_modules, the keyHash matches our key, and no balance moved — but there is no block to open. - The contents of the allowlist are not readable from chain. The Altana account hash-commits its permissions. What is public is that the key exists and is valid; what proves the contents is the rejection above.
- A receipt cannot distinguish an admin key from a session key — both act as the same wallet
and the Orchestrator does not log the signing keyHash. What closes that gap is that the E2E
script only ever loads the session file, and that the same session was rejected for
transfer, while an admin key never would be.
On the test rig
MockLendingPoolis a lending pool we wrote ourselves. It is ABI-compatible with Aave v3'sgetUserAccountData, and we own the price feeds we dropped to create the danger. The positions and the transactions are real; the pool is not a real lending market, and nothing here proves the Guardian works against Aave.
On the platform
- Testnet only, chainId 97. No private key that has ever touched mainnet is used anywhere.
- Deployed, but "deployed" is doing less work than it sounds. Four hosts answer over TLS:
the landing page and the marketplace on Vercel, the backend and the agent endpoints through
nginx on a VPS. The backend serving means the catalogue and the health endpoints answer. It
does not mean an agent runs on a schedule: only
fuguguardianis in the running stack. - No 8004scan API key yet — we are on the anonymous tier, 30 requests/minute. It is used only
to find registration tx hashes. Calls to 8004scan must send a browser
User-Agentor the API answers HTTP 500 (not 429), and they always go through the backend, never from the browser. - The character art is hand-written parametric SVG from
docs/brand/generate-svg.py. Zero images came from a generative model — both image MCP servers were disconnected when that work ran, four attempts, all failed. The prompts indocs/brand/image-prompts.mdhave never been executed and are therefore an unverified specification, not a proven recipe. - CI now runs every suite on every push, and a deploy to the VPS follows a green run on
main. Each job asserts its suite has not lost tests, so adescribe.skipor a glob that stops matching shows up as a failure instead of a quieter green. - Test counts are not written into this document any more. They went stale three times in a
single day. The baselines CI asserts against live in
.github/workflows/ci.yml, and each job fails when its suite loses tests, so that file cannot drift the way a table here does. - Licensed GPL-3.0-or-later; see Licence.
| Package | Stack | How to run |
|---|---|---|
contracts/ |
Solidity 0.8.30 · Foundry (forge 1.7.1) · OpenZeppelin 5.7.0 · UUPS proxies · ERC-7201 namespaced storage · Chainlink price feeds | cd contracts && forge test |
ai/fuguguardian/ |
TypeScript · BNB Agent Studio (@bnbagent/studio-cli) · Altana SDK 0.7.1 · viem · vitest · dGrid (OpenAI-compatible) |
pnpm test |
ai/fugurebalancer/, ai/fugugrid/, ai/fuguyield/ |
same | pnpm test |
ai/fugubroker/, ai/fugutrader/ |
same, plus ERC-8183 and x402 | pnpm test |
ai/fugupilot/, ai/fugumeter/, ai/fugusteward/ |
same, without Studio scaffolding yet | pnpm test |
backend/ |
Hono · Postgres + Drizzle · Redis · viem · vitest · Docker Compose | cd backend && pnpm test |
frontend/ |
Next.js 16 · React 19 · Tailwind v4 · wagmi + Reown · TanStack Query · Playwright E2E · bun | bun --cwd frontend dev |
landingpage/ |
React · Vite · Tailwind v4 · bun | bun --cwd landingpage dev |
video/ |
Remotion · Chrome DevTools Protocol capture · ElevenLabs | npm --prefix video run render |
Every suite runs in CI on every push, with a baseline that fails when a suite loses tests.
The current totals are in .github/workflows/ci.yml.
Redis is up in Compose but no code uses it yet — it is staged for the BullMQ scheduler so
that work does not have to touch docker-compose.yml again.
Infrastructure notes that cost us time, so they cost you none:
RPC_URLmust be overridden. The SDK default points at abinance.orgdomain that is blocked from Indonesia. Usehttps://data-seed-prebsc-1-s1.bnbchain.org:8545.- An empty
calls: []on an Altana session means unlimited permission. Always write an explicit allowlist. This is the single sharpest footgun in the whole stack. - Both 8004scan and dGrid reject requests without a browser
User-Agent— 8004scan with a misleading HTTP 500, dGrid with a 403.
| File | Contents |
|---|---|
docs/specs/2026-09-08-fugugent-design.md |
Architecture spec — binding authority |
docs/research/00-decisions.md |
13 locked decisions + dGrid test results |
docs/e2e/2026-09-08-e2e-testnet.md |
Every on-chain claim in this README, with its full working |
docs/research/05-competitive-landscape.md |
Virtuals, Olas, Almanak, Giza/ARMA, Agentverse — sourced |
docs/brand/puff-levels.md |
The five puff levels, all six visual channels |
docs/setup/ENVIRONMENT.md |
Credentials layout, verified addresses, network constants |
docs/phase2/TRACKING.md |
BNB Chain Phase 2 tracking: events, topic0s, API, team wallets |
docs/phase2/MAINNET.md |
The mainnet migration plan |
Most documents in docs/ are written in Indonesian; identifiers and code are English.
Solo.
| Name | Role | Links |
|---|---|---|
| Axel Urwawuska Atarubby | Everything: contracts, agents, backend, both front ends, infrastructure | GitHub · X · Telegram @lexilexy |
Project account: @hellofuguai on X.
HelloFugu — the fish puffs up as the risk does.
Built on BNB Chain testnet for The Smart Money Era: Build the Era.
Five verified contracts · one rescued position · one rental settled into escrow · one session key that was told no by a contract we do not control.
Twenty agents listed. Five answer as read-only endpoints. One has ever sent a transaction.
Every claim on this page links to something you can check without asking us.
GPL-3.0-or-later. The full text is in LICENSE.
This is not a preference, it is an obligation we chose to meet rather than work around.
ai/fugutrader imports @altananetwork/x402-server, which is GPL-3.0-or-later, into
src/x402/merchant.ts and src/x402/route.ts. Linking GPL code into a distributed work makes
that work a derivative, so either the whole repository goes GPL or the seller side gets
rewritten without that package. We took the licence.
What that means for anyone reading this: you may use, study, modify and redistribute this code, and if you distribute a modified version you have to offer the source under the same terms.
The contracts are the exception, and deliberately so. Every file in contracts/src carries
// SPDX-License-Identifier: MIT, and those exact bytes are what is published and verified on
BscScan. MIT is compatible with GPL-3.0 in the direction that matters here: MIT code can be
included in a GPL work. Changing the header would change the source hash and break verification
against what is already deployed, so it stays as it is.