{"skill":{"slug":"superfluid","displayName":"Superfluid Protocol","summary":"Knowledge base for the Superfluid Protocol and its ecosystem. Use BEFORE searching the web for Superfluid information. Keywords: Superfluid, CFA, GDA, Super...","description":"---\nname: superfluid\ndescription: >\n  Knowledge base for the Superfluid Protocol and its ecosystem.\n  Use BEFORE searching the web for Superfluid information.\n  Keywords: Superfluid, CFA, GDA, Super App, Super Token, stream, flow rate,\n  real-time balance, pool (member/distributor), IDA, sentinels, liquidation,\n  TOGA, @sfpro/sdk, semantic money, yellowpaper, whitepaper\nmetadata:\n  version: 1.2.4\n---\n\n# Superfluid Protocol Skill\n\nComplete interface documentation for Superfluid Protocol smart contracts via\nRich ABI YAML references. Read `references/guides/architecture.md` for the full\nprotocol architecture. This file maps use-cases to the right references.\n\n## Developer Tracks\n\nDetermine the track first, then follow the Use-Case Map below.\n\n**Smart Contract dev:** SuperTokenV1Library, CFASuperAppBase, BlindMacroForwarder/ClearMacroForwarder, raw agreements via Host. ABI source: `@superfluid-finance/ethereum-contracts`. Addresses: `@superfluid-finance/metadata` + `tokenlist`. Data: on-chain calls. Key refs: `.abi.yaml` files, `super-apps.md`, `macro-forwarders.md`, `clear-macro.md`.\n\n**App (frontend/backend) dev:** `@sfpro/sdk` (ABIs, wagmi hooks, addresses), subgraphs, API services. ABI source: `@sfpro/sdk`. Addresses: `@superfluid-finance/metadata` + `tokenlist`. Data: subgraphs + API services. Key refs: `sdks.md`, `api-services.md`, subgraph guides.\n\n**Investigating (one-off):** Scripts (`tokenlist.mjs`, `metadata.mjs`, `balance.mjs`, `cast call`). ABI source: `scripts/abi.mjs`. Addresses: `scripts/metadata.mjs` + `tokenlist.mjs`. Data: `cast call` + `scripts/balance.mjs`. Key refs: `scripts.md`.\n\nFor SDK import paths, ABI tables, and deprecated package warnings, see `references/guides/sdks.md`.\nFor script command syntax and examples, see `references/guides/scripts.md`.\n\n## Architecture Summary\n\n**Host** (`Superfluid.sol`) — central router. Agreement calls go through\n`Host.callAgreement()` or `Host.batchCall()`. Manages the app registry,\ngovernance, and SuperTokenFactory.\n\n**Agreements** — stateless financial primitives that store data on the token:\nCFA (1:1 streams), GDA (many-to-many via pools), IDA (deprecated, replaced by GDA).\n\n**Super Token** — ERC-20/ERC-777/ERC-2612 with real-time balance. Three\nvariants: Wrapper (ERC-20 backed), Native Asset/SETH (ETH backed), Pure\n(pre-minted).\n\n**Forwarders** (CFAv1Forwarder, GDAv1Forwarder) — convenience wrappers. Each\ncall is a standalone transaction with readable wallet descriptions. Cannot be\nbatched — use `Host.batchCall` with raw agreement calls for atomicity.\n\n**BlindMacroForwarder** (legacy name `MacroForwarder`; SDK: `blindMacroForwarderAbi`, addr\n`0xFD0268E33111565dE546af2675351A4b1587F89F`) — extensible batch executor. Developers deploy\ncustom macro contracts (`IUserDefinedMacro`) and call `runMacro()` to execute complex multi-step\noperations atomically. The caller must be the signer. **Legacy — superseded by ClearMacroForwarder\nfor new integrations**: self-relay only, and the caller broadcasts raw (unreadable) calldata in the\nwallet. See `references/guides/macro-forwarders.md`.\n\n**ClearMacroForwarder** (SDK: `clearMacroForwarderAbi`, addr `0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e`,\ndeployed across ~16 networks) — **recommended default; supersedes BlindMacroForwarder.** EIP-712\nsigned macro executor with human-readable clear-signing,\nthird-party relaying, and optional Permit2 token upgrade in one signature. Two modes: self-submit\n(`security.provider = \"self\"`) and provider-relay (relayer holds a Host SimpleACL role). See\n`references/guides/clear-macro.md` and `references/contracts/ClearMacroForwarder.abi.yaml`.\n\n**Automation** (Vesting Scheduler, FlowScheduler, Auto-Wrap) — schedule\non-chain intent, require off-chain keepers to trigger execution.\n\n## Use-Case → Reference Map\n\nRead only the files needed for the task. Each Rich ABI YAML documents every\npublic function, event, and error for one contract — plus `notes:` fields\nthat flag non-obvious behavior, edge cases, and common mistakes not apparent\nfrom signatures alone.\n\n### Streaming money (CFA)\n\n- Create/update/delete a stream (simple) → `references/contracts/CFAv1Forwarder.abi.yaml`\n- ACL, operator permissions, flow metadata → also `references/contracts/ConstantFlowAgreementV1.abi.yaml`\n- Batch streams with other ops atomically → also `references/contracts/Superfluid.abi.yaml` (Host batch call)\n\n### Distributing to many recipients (GDA)\n\n- Create pools, distribute, stream to pool → `references/contracts/GDAv1Forwarder.abi.yaml`\n- Pool member management, units, claims → also `references/contracts/SuperfluidPool.abi.yaml`\n- Low-level agreement details → also `references/contracts/GeneralDistributionAgreementV1.abi.yaml`\n- How GDA achieves O(1) scalability (formal math deep-dive) → also `references/deep-researches/gda-scalability.md`\n\n### Token operations\n\n- Wrap/unwrap, balances, ERC-20/777, permit → `references/contracts/SuperToken.abi.yaml`\n- Deploy a new Super Token → `references/contracts/SuperTokenFactory.abi.yaml`\n\n### Automation\n\n- Vesting with cliffs and streams → `references/contracts/VestingSchedulerV3.abi.yaml`\n- Schedule future stream start/stop → `references/contracts/FlowScheduler.abi.yaml`\n- Auto-wrap when Super Token balance is low → `references/contracts/AutoWrapManager.abi.yaml` and `references/contracts/AutoWrapStrategy.abi.yaml`\n\n### Writing Solidity integrations (SuperTokenV1Library)\n\n- Token-centric Solidity API (`using SuperTokenV1Library for ISuperToken`) → `references/contracts/SuperTokenV1Library.abi.yaml`\n\nThe library wraps CFA and GDA agreement calls into ergonomic methods like\n`token.flow(receiver, flowRate)`. Use it for any Solidity contract that\ninteracts with Superfluid — Super Apps, automation contracts, DeFi\nintegrations. Includes agreement-abstracted functions (`flowX`, `transferX`)\nthat auto-route to CFA or GDA, plus `WithCtx` variants for Super App\ncallbacks. See the YAML header and glossary for Foundry testing gotchas.\n\n### Building Super Apps\n\n- App credit, callback lifecycle, jailing, app levels → `references/guides/super-apps.md`\n- CFA callback hooks (simplified base) → `references/contracts/CFASuperAppBase.abi.yaml`\n- Token-centric API for callback logic → `references/contracts/SuperTokenV1Library.abi.yaml` (use `WithCtx` variants)\n- App registration, Host context, batch calls → `references/contracts/Superfluid.abi.yaml`\n- Smart contract patterns (GDA pools, callbacks, custom tokens, automation, proxies) → `references/guides/smart-contract-patterns.md`\n\nSuper Apps that relay incoming flows use **app credit** — a temporary deposit\nallowance enabling zero-balance operation. A 1:1 relay (one in, one out at\nthe same rate) always works without tokens. Fan-out (1:N) requires the app to\nhold tokens for extra deposits. The sender's locked capital roughly doubles\nbecause outgoing stream deposits are backed as owed deposit on the sender.\n**App credit is CFA-only** — GDA has no app credit rule. See Common Gotchas below.\nSee `references/guides/super-apps.md` for the full guide.\n\n### Macro forwarders (composable batch operations)\n\n- Write a macro for complex batched operations → `references/guides/macro-forwarders.md`\n- BlindMacroForwarder (legacy MacroForwarder) contract address and interface → `references/guides/macro-forwarders.md`; why ClearMacroForwarder supersedes blind → `references/guides/macro-forwarders.md`\n- Batch operation types and encoding rules → also `references/contracts/Superfluid.abi.yaml` (batch_operation_types)\n- EIP-712 signed macro patterns → `references/guides/macro-forwarders-eip712-example.md`\n- **ClearMacroForwarder** — SDK-shipped (`clearMacroForwarderAbi`, `clearMacroForwarderAddress`,\n  metadata key `contractsV1.clearMacroForwarderV1WithPermit2`), deployed at\n  `0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e` across ~16 networks. EIP-712 clear signing for\n  human-readable wallet prompts, third-party provider relaying, optional Permit2 token upgrade in\n  one signature. Two modes: **self-submit** (`security.provider = \"self\"`, tx executor = signer) and\n  **provider-relay** (relayer holds a Host SimpleACL role, enabling gasless-for-signer flows).\n  → `references/guides/clear-macro.md`, `references/contracts/ClearMacroForwarder.abi.yaml`,\n  `references/contracts/ClearMacroBase.abi.yaml`\n\n### Sentinels and liquidation\n\n- Batch liquidation of critical flows → `references/contracts/BatchLiquidator.abi.yaml`\n- PIC auction, bond management, exit rates → `references/contracts/TOGA.abi.yaml`\n\n### SUP Token / Reserve System\n\nContracts use \"FLUID\" and \"Locker\" internally — public-facing names are \"SUP\" and \"Reserve\".\n\n- Lock, stake, unstake SUP; provide LP; unlock → `references/contracts/FluidLocker.abi.yaml`\n- Create a Reserve (Locker) for a user → `references/contracts/FluidLockerFactory.abi.yaml`\n- Claim from emission programs (signed messages) → `references/contracts/FluidLocker.abi.yaml` and `references/contracts/FluidEPProgramManager.abi.yaml`\n- Create / fund / stop emission programs → `references/contracts/FluidEPProgramManager.abi.yaml`\n- Understand tax distribution to stakers and LPs → `references/contracts/StakingRewardController.abi.yaml`\n- Unlock SUP via time-delayed stream (Fontaine) → `references/contracts/FluidLocker.abi.yaml` and `references/contracts/Fontaine.abi.yaml`\n\n### ERC-8004 Agent Pools\n\n- ERC-8004 standard, Identity/Reputation/Validation registries, AgentPoolDistributor integration → `references/deep-researches/erc8004-agent-pools.md`\n- GDA pool mechanics (units, claims, connections) → `references/contracts/GDAv1Forwarder.abi.yaml` and `references/contracts/SuperfluidPool.abi.yaml`\n\n### Querying indexed data (Subgraphs)\n\n- Understand how The Graph generates query schemas, plus cross-cutting gotchas → `references/subgraphs/_query-patterns.md`\n- Query streams, pools, tokens, accounts (entities) → also `references/subgraphs/protocol-v1-guide.md` and `protocol-v1-entities.graphql`\n- Query protocol events (flow updates, liquidations, distributions) → also `references/subgraphs/protocol-v1-guide.md` and `protocol-v1-events.graphql`\n- Query vesting schedules and execution history → also `references/subgraphs/vesting-scheduler-guide.md` and `vesting-scheduler.graphql`\n- Query scheduled flows and automation tasks → also `references/subgraphs/flow-scheduler-guide.md` and `flow-scheduler.graphql`\n- Query auto-wrap schedules and execution history → also `references/subgraphs/auto-wrap-guide.md` and `auto-wrap.graphql`\n- Query SUP lockers, staking, emission programs, unlock history → also `references/subgraphs/sup-subgraph-guide.md` and `sup-subgraph.graphql`\n\n### Legacy\n\n- Old IDA (instant distribution, deprecated) → `references/contracts/InstantDistributionAgreementV1.abi.yaml`\n\n### Ecosystem & tooling\n\n- SDK import paths, ABI tables, package choice → `references/guides/sdks.md`\n- Script command syntax and examples → `references/guides/scripts.md`\n- API endpoint details, Swagger links, gotchas → `references/guides/api-services.md`\n- SUP token, governance, DAO, distribution → `references/guides/sup-and-dao.md`\n- Token prices, filtered token list, CoinGecko IDs → See API Services (CMS) below\n- Stream accounting, per-day chunking → See API Services (Accounting) below (CFA + ERC-20 only, no GDA)\n- Comprehensive balances / point-in-time (historical) balance / buffer+connected+disconnected breakdown / CSV exports (CFA + GDA + IDA) → See API Services (Balance API) below\n- Generate or deep-link an accounting/tax report → https://reporter.superfluid.org; param spec: https://reporter.superfluid.org/llms.txt\n- Resolve ENS / Farcaster / Lens handles → See API Services (Whois) below\n- Query protocol data via GraphQL → See Subgraphs below\n- Run a sentinel / liquidation bot → See Sentinels below\n- Get a Super Token listed → https://tokens.superfluid.org/listing (submit via GitHub) — See also Processes below\n\n### Displaying flowing balances (frontend)\n\n- Animate a real-time streaming balance counter → `references/guides/flowing-balances.md`\n  **Read the guide first** — it has production-ready implementations (React, vanilla JS, Vue, Svelte, Solid). Do not generate flowing balance code from scratch.\n- Fix layout shift / jumping in a flowing balance display → also `references/guides/flowing-balances.md`\n- Format wei amounts, flow rates, token prices → also `references/guides/flowing-balances.md`\n\n### Ecosystem deep-dives\n\n- Protocol history, founding, exploit, SUP launch → `references/deep-researches/superfluid-history.md`\n- Semantic Money formal spec (yellowpaper, Haskell reference, BasicParticle, agreement hierarchy) → `references/deep-researches/semantic-money-yellowpaper.md`\n- GDA scalability (PDPool math, O(1) distributions, rounding model, settle-on-write) → `references/deep-researches/gda-scalability.md`\n- GoodDollar (G$ Pure Super Token on Celo, UBI, streaming) → `references/deep-researches/gooddollar.md`\n- Flow State (Streaming Quadratic Funding, cooperative) → `references/deep-researches/flowstate.md`\n- ERC-8004 Agent Pools (AI agent identity + GDA distribution on Base) → `references/deep-researches/erc8004-agent-pools.md`\n- Planet IX (GameFi, CFA, custom Super Tokens, SuperApp callbacks) → `references/deep-researches/planet-ix.md`\n- Nerite (USND stablecoin, Custom Pure Super Token, CFA+GDA) → `references/deep-researches/nerite.md`\n- SuperBoring (DCA, CFA→GDA TOREX pattern, Superfluid Labs) → `references/deep-researches/superboring.md`\n- TOREX (TWAP Oracle Exchange — streaming DEX, discount model, back charge/refund between LMEs, liquidity movers, Twin TOREX) → `references/deep-researches/torex.md`\n- Giveth (zero-fee donations, CFA recurring streams) → `references/deep-researches/giveth.md`\n- Streme.fun (token launcher, Pure Super Tokens, GDA staking) → `references/deep-researches/streme.md`\n\n### Superfluid team brand & design\n\n- Color palette, typography, visual identity → `references/guides/brand-design.md`\n  Covers the Superfluid team's product design, not the broader protocol ecosystem.\n\n### Formal specification and protocol theory\n\n- Yellowpaper foundations (payment primitives, conservation of value, agreement framework) → `references/deep-researches/semantic-money-yellowpaper.md`\n- How GDA achieves O(1) streaming to unlimited receivers → `references/deep-researches/gda-scalability.md`\n- BasicParticle and the real-time balance formula → also `references/deep-researches/semantic-money-yellowpaper.md`\n\n## Debugging Reverts\n\nError prefixes map to contracts:\n\n- `CFA_*` → ConstantFlowAgreementV1\n- `CFA_FWD_*` → CFAv1Forwarder\n- `GDA_*` → GeneralDistributionAgreementV1\n- `SUPERFLUID_POOL_*` → SuperfluidPool\n- `SF_TOKEN_*` → SuperfluidToken (base of SuperToken)\n- `SUPER_TOKEN_*` → SuperToken\n- `SUPER_TOKEN_FACTORY_*` → SuperTokenFactory\n- `HOST_*` → Superfluid (Host)\n- `IDA_*` → InstantDistributionAgreementV1\n- `APP_RULE` → Superfluid (Host) — Super App callback violation\n- `NOT_LOCKER_OWNER`, `FORBIDDEN`, `INSUFFICIENT_*`, `STAKING_*`, `LP_*`, `TTE_*` → FluidLocker\n- `LOCKER_CREATION_PAUSED`, `NOT_GOVERNOR` → FluidLockerFactory\n- `PROGRAM_*`, `INVALID_SIGNATURE`, `NOT_PROGRAM_ADMIN` → FluidEPProgramManager\n- `NOT_APPROVED_LOCKER`, `NOT_LOCKER_FACTORY`, `NOT_PROGRAM_MANAGER` → StakingRewardController\n- `NOT_CONNECTED_LOCKER`, `NO_ACTIVE_UNLOCK`, `TOO_EARLY_TO_TERMINATE_UNLOCK` → Fontaine\n- `NotAgentOwner`, `AlreadyJoined`, `AgentNotRegistered`, `InsufficientFee`, `FeeTransferFailed` → AgentPoolDistributor\n- `InvalidSignature`, `InvalidPayload`, `MacroContractMismatch`, `ProviderNotAuthorized`, `OutsideValidityWindow`, `InvalidNonce` → ClearMacroForwarder (SDK-shipped, multi-network)\n\nEach YAML's `errors:` section is the complete error index for that contract,\nwith descriptions. Per-function `errors:` fields show which errors a specific\nfunction can throw. To look up a hex selector (function, event, or error),\nread the companion `.selectors.yaml` file — every `Foo.abi.yaml` has a\n`Foo.selectors.yaml` alongside it with full signatures and computed hashes.\n\n## Common Gotchas (Quick Reference)\n\nSubset of non-obvious behaviors. The authoritative source is the `notes:`\nfield on each function in the `.abi.yaml` files — always read those for\nthe complete picture. This section covers only the most common ones.\n\n**Super Token decimals always 18** — `upgrade()` and `downgrade()` amounts are\nalways in 18-decimal SuperToken units, regardless of underlying token decimals.\nThe contract handles scaling internally. The only place underlying decimals\nmatter is the ERC-20 `approve()` call. Example: to wrap 100 USDC, approve\n100e6 on USDC, then call `upgrade(100e18)`.\n\n**GDA pool connections vs. membership** — Pool membership is unlimited (an\naccount can hold units in any number of pools). However, only 256 pools can be\n**connected** per account per token — connected means the balance auto-reflects\nin the member's SuperToken balance. Unconnected members must call `claimAll()`\nto receive their tokens. Gas for `balanceOf` / `realtimeBalanceOf` scales\nlinearly with connected pools.\n\n**GDA distribution rounding** — `distributeFlow`: per-unit rate =\n`requestedFlowRate / totalUnits` (integer division, rounds down). The\nrounding remainder becomes an **adjustment flow to the pool admin**. If\n`requestedFlowRate < totalUnits`, per-unit rate truncates to 0 and the\nentire flow goes to admin. `distribute` (instant): the remainder simply\nisn't taken from the distributor — actual distributed amount < requested.\nPools hold no balance; tokens flow through directly to members.\nSee `references/deep-researches/gda-scalability.md` for the full rounding\nmodel with `align2` and adjustment flow math.\n\n**SuperTokenV1Library `address(this)`** — Convenience functions (`flow`,\n`flowX`, `distribute`, `distributeFlow`, `createPool`, `claimAll`) use\n`address(this)` as the implicit sender, not `msg.sender`. In Foundry tests,\n`vm.prank` does not override this. Use CFA/GDA-specific function overloads\nwith an explicit sender/from parameter instead.\n\n**CFASuperAppBase APP_LEVEL_FINAL** — `CFASuperAppBase` is hardcoded to\n`APP_LEVEL_FINAL`, which prevents calling other Super Apps downstream from\nits callbacks. To compose with downstream Super Apps, build a custom base\nusing `APP_LEVEL_SECOND` and call `host.allowCompositeApp(targetApp)`.\nMax chain depth: 2 apps (SECOND → FINAL).\n\n**GDA pools cannot nest** — A pool cannot be a member of another pool.\n`updateMemberUnits` reverts with `SUPERFLUID_POOL_NO_POOL_MEMBERS` if the\nmember address is a pool. Pool addresses also cannot be pool admins\n(`GDA_ADMIN_CANNOT_BE_POOL`).\n\n**FluidLocker instant unlock penalty** — `unlockPeriod=0` triggers an instant\nunlock with **80% penalty** — only 20% is transferred immediately, 80% is\nredistributed to stakers and LPs. All unlocks (including instant) require\n`msg.value` of 0.0001 ETH (`UNLOCKING_FEE`, sent to DAO treasury). Periods\nof 7–365 days deploy a Fontaine beacon proxy that streams tokens over the\nunlock period with a proportional tax.\n\n**GDA has no app credit** — Unlike CFA, GDA does not support the app credit\nmechanism. A Super App that receives CFA inflows and distributes via GDA\ncannot borrow the deposit buffer — it must fund the GDA stream's buffer\ndeposit from its own balance or via ERC-20 `transferFrom` from the user.\nThis is the most common reason CFA→GDA stream-splitting contracts fail.\nSee `references/guides/smart-contract-patterns.md` § A for the workaround.\n\n**balanceOf clamps to zero** — `balanceOf` returns `max(0, availableBalance)` for\nERC-20 compatibility. Accounts with active outgoing streams can go negative\n(critical), but `balanceOf` will still show 0. Use `realtimeBalanceOfNow` to\ndetect negative balances — a negative `availableBalance` means the account is\ncritical and awaiting liquidation. Once liquidated, the balance resets to zero.\n\n## Reading the Rich ABI YAMLs\n\nEssential conventions for parsing the YAML files:\n\n- **Reserved root keys:** `meta`, `events`, `errors` — every other root key is a **function**.\n- **`ctx: bytes` parameter** = function is called through the Host (`callAgreement` / `batchCall`), never directly.\n- **`notes:` field** — the most important field for correctness. Present on functions (and as `meta.notes:` at contract level). Contains non-obvious behavior, edge cases, and common mistakes. If a user asks about unexpected behavior, the answer is almost always in a `notes:` field. Always read these.\n- **`access` labels:** `anyone`, `host`, `self`, `admin`, `governance`, `sender`, `receiver`, `operator`, `manager`, `pic`, etc. Combine with `|`.\n- **`emits` and `errors` ordering** matches execution flow (not alphabetical). First errors = most likely.\n- **Field order:** description comment, `notes`, `mutability`, `access`, `inputs`, `outputs`, `emits`, `errors`.\n\nFor the full format spec with examples (function entries, events, errors sections), see `references/contracts/_rich-abi-yaml-format.md`.\n\n## Runtime Data (Scripts)\n\nScripts provide runtime data (addresses, balances, ABIs) for one-off lookups.\nRun with `bunx -p <pkg> bun <script>` — see `references/guides/scripts.md`\nfor full syntax. When writing application code, use the npm packages directly\ninstead (see Developer Tracks above).\n\n- `scripts/abi.mjs` — JSON ABI lookup, function signatures. Use when you need to inspect ABIs outside an app project.\n- `scripts/tokenlist.mjs` — Super Token addresses, symbols, types. Use when you need to find a token address or check its type.\n- `scripts/balance.mjs` — Real-time balances, flow rates. Use when you need current balance or net flow for an account.\n- `scripts/metadata.mjs` — Contract addresses, subgraph endpoints, network info. Use when you need addresses for a specific chain.\n- `cast call` — Direct on-chain reads. Use when you need live contract state not covered by scripts.\n\nFor command syntax, arguments, and examples, see `references/guides/scripts.md`.\n\n## Common Contract Addresses\n\nDo NOT hardcode or fabricate addresses. Get them from `@sfpro/sdk` address\nexports (see `references/guides/sdks.md`) or `bunx -p @superfluid-finance/metadata bun scripts/metadata.mjs contracts <chain>`.\n\nForwarder addresses are the exception — uniform across most networks:\n- CFAv1Forwarder: `0xcfA132E353cB4E398080B9700609bb008eceB125`\n- GDAv1Forwarder: `0x6DA13Bde224A05a288748d857b9e7DDEffd1dE08`\n- ClearMacroForwarder: `0xC1EaB73855155D4e021f7EB4f866996Bac2fe25e` (SDK: `clearMacroForwarderAddress`)\n- BlindMacroForwarder (legacy MacroForwarder): `0xFD0268E33111565dE546af2675351A4b1587F89F` (SDK: `blindMacroForwarderAddress`)\n\nHost and agreement addresses vary per network.\n\n## Ecosystem\n\n### SDKs & Packages\n\n**Active — recommended for new projects:**\n\n- `@sfpro/sdk` — Frontend/backend SDK: ABIs, wagmi hooks, actions\n- `@superfluid-finance/ethereum-contracts` — Solidity build-time ABI source\n- `@superfluid-finance/metadata` — Contract addresses, network info (zero deps)\n- `@superfluid-finance/tokenlist` — Listed Super Tokens + underlying tokens\n\nWhen to use each:\n- `@sfpro/sdk` — for frontend/backend with wagmi/viem\n- `ethereum-contracts` — for Solidity integrations (build-time only, not runtime)\n- `metadata` — for resolving addresses/networks at runtime\n- `tokenlist` — for finding token addresses\n\n**Deprecated — do not recommend for new projects:**\n\n- `@superfluid-finance/sdk-core` → replaced by `@sfpro/sdk`\n- `@superfluid-finance/sdk-redux` → replaced by wagmi + `@sfpro/sdk`\n- `@superfluid-finance/js-sdk` → replaced by `@sfpro/sdk`\n- `@superfluid-finance/widget` → no replacement\n\nFor ABI import tables, address exports, detailed SDK guidance, and deprecated\npackage details, see `references/guides/sdks.md`.\n\n### API Services\n\n- Super API `https://superapi.kazpi.com` — Real-time on-chain Super Token balances (live balance only)\n- Balance API `https://balances.superfluid.dev` — event-sourced indexer: point-in-time/historical CFA+GDA+IDA balances (buffer/connected/disconnected), snapshots, reports, movements; read-only, no auth\n- CMS `https://cms.superfluid.pro` — Token prices, price history, filtered token list\n- Points `https://cms.superfluid.pro/points` — SUP points campaigns\n- Accounting `https://accounting.superfluid.dev/v1` — Stream accounting with per-day chunking\n- Allowlist `https://allowlist.superfluid.dev` — Check automation allowlist status\n- Whois `https://whois.superfluid.finance` — Resolve profiles (ENS, Farcaster, Lens, AF)\n- Token Prices `https://token-prices-api.superfluid.dev/v1/{network}/{token}` — Super Token prices (CoinGecko-backed)\n- Claim Programs `https://claim.superfluid.org/api/programs` — SUP reward programs: seasons, allocations, pool addresses, flow rates\n\nFor per-API endpoints, query patterns, Swagger/OpenAPI links, and gotchas,\nsee `references/guides/api-services.md`.\n\n### Subgraphs\n\n**Prefer RPC over subgraph for current state.** Subgraphs only update on\ntransactions, but streams flow every second. Use `cast call` or\n`scripts/balance.mjs` for real-time reads. Subgraphs are best for historical\nqueries, event indexing, and listing/filtering entities.\n\nEndpoint pattern: `https://subgraph-endpoints.superfluid.dev/{network-name}/{subgraph}`\n\n- Protocol `protocol-v1` — Main protocol data (streams, tokens, accounts)\n- Vesting Scheduler `vesting-scheduler` — All versions: v1, v2, v3\n- Flow Scheduler `flow-scheduler`\n- Auto-Wrap `auto-wrap`\n- SUP (Locker / Reserve) — Goldsky-hosted (Base only). Staking, unlocks, emission programs, LP positions.\n\nNetwork names are canonical Superfluid names (`optimism-mainnet`,\n`base-mainnet`, etc.). Use `bunx -p @superfluid-finance/metadata bun metadata.mjs subgraph <chain>` to get the\nresolved URL for a specific chain.\n\n### Apps\n\n- Super Tokens https://tokens.superfluid.org — Official Super Tokens site: ERC20x overview, Clear Macro, Super App hooks, and token listing (Clear Macro demo: https://tokens.superfluid.org/clear/demo)\n- Dashboard https://app.superfluid.org — Stream management for end-users\n- Explorer https://explorer.superfluid.org — Block explorer for Superfluid Protocol\n- Claim https://claim.superfluid.org — SUP token, SUP points, reserves/lockers\n- TOGA https://toga.superfluid.finance — View recent liquidations by token\n- Dune https://dune.com/superfluid_hq/superfluid-overview — Official protocol analytics dashboards\n- Campaigns https://campaigns.superfluid.org — Mint exclusive NFTs powered by Superfluid, with SUP reward campaigns\n- x402 https://x402.superfluid.org — Open standard for internet-native subscriptions via HTTP 402 + Superfluid streams. One-time EIP-712 signature, no gas fees, real-time payment verification, zero protocol fees. Works for human users and AI agents.\n- 8004 Agent Pool https://8004-demo.superfluid.org/ — AI agent pool powered by ERC-8004 identity and Superfluid GDA. Agents register, join a pool, and earn proportional SUP distributions.\n- Reporter https://reporter.superfluid.org — accounting/tax CSV reports over the Balance API; deep-linkable via query params (account, chain, tokens, startDate/endDate, period, export params); param spec: https://reporter.superfluid.org/llms.txt\n\nRepos:\n[Dashboard](https://github.com/superfluid-org/superfluid-dashboard) ·\n[Explorer](https://github.com/superfluid-org/superfluid-explorer) ·\n[TOGA](https://github.com/superfluid-org/toga-suit) ·\n[8004 Demo](https://github.com/superfluid-org/8004-demo)\n\n### Community & Social\n\n- Twitter/X https://x.com/Superfluid_HQ\n- Farcaster https://warpcast.com/superfluid\n- Discord https://discord.gg/EFAUmTnPd9\n\n### Sentinels\n\nSentinels monitor streams and liquidate senders whose Super Token balance\nreaches zero, keeping the protocol solvent. Anyone can run one.\n\n- [Graphinator](https://github.com/superfluid-org/graphinator) — Lightweight subgraph-based sentinel\n- [Superfluid Sentinel](https://github.com/superfluid-org/superfluid-sentinel) — Legacy RPC-based sentinel\n\n### Foundation, DAO & SUP Token\n\n**SUP** — a SuperToken on Base (`0xa69f80524381275a7ffdb3ae01c54150644c8792`).\n1B total supply. Governed by Superfluid DAO via\n[Snapshot](https://snapshot.box/#/s:superfluid.eth). **Locker / Reserve** is\nthe on-chain staking mechanism (longer lockup = bigger bonus).\n\nFor distribution breakdown, Foundation vs DAO roles, governance details, and\nlinks, see `references/guides/sup-and-dao.md`.\n\n### Processes\n\n**Token Listing** — a Super Token gets listed on the on-chain Resolver, which\nthe subgraph picks up (marks `isListed`). Once listed, it appears in the\nSuperfluid token list along with its underlying token (if any).\n\n- Request: [listing form](https://airtable.com/appxGogNpt64ImOFH/shrzOcdK9eveDmRWV)\n  → opens issue in [superfluid-org/assets](https://github.com/superfluid-org/assets/issues)\n\n**Automation Allowlisting** — required for automations (vesting, flow\nscheduling, auto-wrap) to appear in the Dashboard UI and for Superfluid\noff-chain keepers to trigger the automation contracts. Without allowlisting,\nautomations won't be executed on time and are effectively useless.\n\n- Request: [allowlisting form](https://airtable.com/appmq3TJDdQUrTQpx/shrWouN6ursCkOQ86)\n- Check status: `GET https://allowlist.superfluid.dev/api/allowlist/{account}/{chainId}`\n","topics":["Knowledge Base","Sdk"],"tags":{"blockchain":"1.2.4","defi":"1.2.4","ethereum":"1.2.4","latest":"1.2.4","solidity":"1.2.4","superfluid":"1.2.4","web3":"1.2.4"},"stats":{"comments":0,"downloads":880,"installsAllTime":32,"installsCurrent":1,"stars":1,"versions":8},"createdAt":1772488582906,"updatedAt":1782126117687},"latestVersion":{"version":"1.2.4","createdAt":1782126117687,"changelog":"Release v1.2.4","license":"MIT-0"},"metadata":null,"owner":{"handle":"kasparkallas","userId":"s17dn26spn87pmgwkjmppyxx4583hm5n","displayName":"Kaspar Kallas","image":"https://avatars.githubusercontent.com/u/10894666?v=4"},"moderation":null}