search
Ctrlk
FloeLabs.xyz

swapChangelog

Notable changes and updates to the Floe protocol.

hashtag
Version History

hashtag
v1.7.1 — x402 v2 Wire Protocol Support (May 2026)

The facilitator now negotiates between x402 v1 and x402 v2 per request based on what the merchant returns. Previously, only the v1 bare-requirement envelope was understood, which caused parse failures against modern @x402/hono and other v2-compliant servers — and which made the v2 entries already published in the Floe x402 directoryarrow-up-right unreachable in practice.

What changed:

  • parsePaymentRequired now accepts either a v1 bare PaymentRequirement (single or array) or a v2 { x402Version, accepts, resource, error, extensions } envelope, and normalizes the renamed amount field back to the internal maxAmountRequired shape.

  • On the outbound side, the signed payment header is written as PAYMENT-SIGNATURE when the merchant advertised v2, or X-PAYMENT for v1 — picked automatically per request.

  • The settlement response header (PAYMENT-RESPONSE in v2, X-PAYMENT-RESPONSE in v1) is base64-decoded when it carries a v2 SettlementResponse; the transaction field becomes the recorded tx hash. v1 strings still pass through unchanged.

  • GET /v1/proxy/check surfaces the negotiated x402Version and, on parse failure, a typed code (invalid_base64 / invalid_json / no_compatible_requirement) so misformatted upstreams are diagnosable without a redeploy.

What didn't change:

  • EIP-3009 TransferWithAuthorization typed data and signing — identical between v1 and v2.

  • Reservation lifecycle (RC-12), idempotency keys, rate limits, agent registration, and credit-line opening flows.

  • The supported asset (USDC) and network (Base mainnet); CAIP-2 "eip155:8453" and the short name "base" are both still accepted.

Why this matters: developers running v2 merchants no longer hit "Failed to parse PAYMENT-REQUIRED header" against Floe, and the directory's v2 entries (Firecrawl, Exa, Soundside, Freepik, and the rest) now negotiate correctly. Spec refs: x402-specification-v2.mdarrow-up-right, transports-v2/http.mdarrow-up-right, CDP migration guidearrow-up-right.

hashtag
v1.7.0 — Unified Agent Registration + Managed Credit Line (May 2026)

The legacy single-agent registration path is removed. All agent provisioning now flows through the same dashboard surface that multi-agent uses (POST /v1/developer/agents), authenticated by a dashboard session, a floe_live_* developer key, or a wallet signature. Provisioning is intentionally decoupled from credit-line opening: a new server-signed endpoint mints the facility loan from the agent's managed Privy wallet (USDC/USDC market).

Removed (breaking):

  • POST /v1/agents/pre-register and POST /v1/agents/register — replaced by POST /v1/developer/agents (provision) + POST /v1/developer/agents/:id/keys (mint).

  • developers.agentApiKeyHash legacy fallback in api_key_auth middleware — all agents now resolve via the api_keys table.

Added:

  • POST /v1/developer/agents/:agentId/open-credit-line — server-signs registerBorrowIntent from the agent's managed Privy wallet in the USDC/USDC market. Body: { depositRaw, maxLtvBps?, maxRateBps? }. Default LTV 9500 (95%, the same-token market cap). Returns { loanId, registerTxHash, approveTxHash?, principalRaw, status: 'pending_on_chain' }. The existing FacilityLoanReconciler advances the row to pending_match once the receipt confirms; the solver matches it asynchronously. Idempotent via the Idempotency-Key header. This is the step that makes a managed agent's creditIn non-zero — without calling it, /proxy/fetch returns insufficient_balance.

SDK migration (floe-agent v0.4.0 / floe-agentkit-actions v0.4.0):

  • New subcommands: floe-agent register, agents, use, rotate, revoke, open-credit-line. Each developer can register up to 5 agents from the CLI.

  • Per-agent API keys now live in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) via @napi-rs/keyring / keyring. Falls back to FLOE_AGENT_KEY_<NAME> env vars in headless environments.

  • grant_credit_delegation action rewired to the new provisioning flow. The schema gains a required name; the facilitatorAddress / collateralToken / collateralApproval fields are removed (the server's Privy wallet handles on-chain delegation and collateral). Return message points users at the new open_credit_line step.

  • New open_credit_line action — calls POST /v1/developer/agents/:id/open-credit-line with wallet-signed auth and prints the resulting loanId + tx hashes. Available in both TS and Python SDKs.

  • revoke_credit_delegation and check_credit_delegation unchanged — still pure on-chain operations against the lending matcher.

MCP server (@floelabs/mcp-server):

  • No code change; remote endpoint and stdio mode already accept per-request Bearer tokens. README + .env.example clarify that floe_* agent keys are the recommended credential — floe_live_* developer keys still work but disable the agent-awareness tools.

Why this matters: one registration path, one key model, one explicit "open the credit line" step. Splitting provisioning from credit-line opening makes the lifecycle visible: developers see exactly when their agent gains spendable USDC instead of having it bundled invisibly into registration.

hashtag
v1.6.0 — Same-Token Markets, Fiat On-Ramp, Multi-Agent (May 2026)

Same-Token Markets (Upgrade #13):

  • USDC/USDC market live on Base Mainnet. Deposit USDC, borrow up to 95% as working capital. No price-volatility risk — the oracle returns a hardcoded 1:1 ratio.

  • New protocol constants: SAME_TOKEN_MAX_LTV_BPS (99.5% cap), SAME_TOKEN_MIN_LTV_GAP_BPS (0.5% gap). Normal markets (WETH/USDC, cbBTC/USDC) are completely unaffected.

  • Oracle getPrice() and getPriceChecked() short-circuit for same-token pairs — immune to Chainlink staleness, circuit breaker, and sequencer downtime.

  • Market ID: 0x5027ae5ed5c85380c5dfa34a79915f41f139f4e859f56d15a6f958ea6b662820

  • 4 contracts upgraded: LendingLogicsManager, LendingCalcLib, LendingViewsUpgradeable, PriceOracleUpgradeable

Fiat On-Ramp:

  • Buy USDC from the Developer Dashboard via Coinbase CDP. Credit card, debit card, or bank transfer — USDC lands directly in your agent's wallet on Base. No crypto bridges needed.

  • POST /v1/onramp/session-token mints a CDP session token for authenticated developers

  • Webhook verification via Hook0 HMAC-SHA256 for audit trail

Multi-Agent System:

  • Up to 5 agents per developer, each with independent credit limits, rate caps, and delegation expiry.

  • New API routes: GET/POST /v1/developer/agents, GET /v1/developer/agents/:id, POST /v1/developer/agents/:id/close, key management per agent.

  • Agent modes: managed (new, server-provisioned) and legacy (existing SDK-registered agents).

  • Per-agent session spend limits via PUT /v1/agents/spend-limit.

New Webhook Events:

  • credit.utilization_warning — fires when borrowed principal exceeds 80% of credit limit.

  • delegation.expiry_warning — fires 7 days and 24 hours before operator delegation expires.

hashtag
v1.5.0 — Agent Awareness Primitives (May 2026)

Lets agents reason about their own credit before committing capital. Answers the three rational-agent questions in one round-trip: "do I have credit?", "is this call worth its cost?", "where am I in the loan lifecycle?".

REST API (credit-api.floelabs.xyz):

  • GET /v1/agents/credit-remaining — available USDC, headroom to auto-borrow, utilization in bps, session-cap state.

  • GET /v1/agents/loan-state — coarse state machine: idle | borrowing | at_limit | repaying.

  • GET / PUT / DELETE /v1/agents/spend-limit — operator-defined session ceiling, enforced inside the proxy paid-request transaction.

  • GET / POST / DELETE /v1/agents/credit-thresholds — webhook subscriptions for credit.warning / credit.at_limit / credit.recovered. Atomic hysteresis guarantees exactly-once delivery per edge crossing. Cap of 20 per agent.

  • POST /v1/x402/estimate — preflight an x402-protected URL, return cost + reflection against the calling agent's credit. SSRF-policy-keyed cache for cross-tenant isolation.

SDK Updates:

  • floe-agent (npm) and floe-agentkit-actions (PyPI) updated to 0.3.0 — adds 9 agent-awareness actions to X402ActionProvider. 45 actions total (30 Floe + 15 X402: 6 credit-delegation + 9 agent-awareness).

  • @floelabs/mcp-server (npm) updated to 0.2.0 — adds 9 corresponding MCP tools. 36 tools total.

  • All names are snake_case and identical across REST / MCP / TS / Python: get_credit_remaining, get_loan_state, {get,set,clear}_spend_limit, {list,register,delete}_credit_threshold, estimate_x402_cost.

Docs:

hashtag
v1.4.0 — Unified Developer Platform + x402 Credit Facilitator (April 2026)

Developer Platform:

  • Developer Dashboard at dev-dashboard.floelabs.xyzarrow-up-right — manage API keys, webhooks, and agents via wallet sign-in.

  • API Keys (floe_live_*) — programmatic access without per-request wallet signing. See API Keys.

  • Webhooks — push notifications for loan events (loan.health_warning, loan.expiry_warning, loan.liquidated, loan.repaid) with HMAC-signed payloads and retry. See Webhooks.

  • Unified API — all endpoints at credit-api.floelabs.xyz under one base URL, dual auth (floe_live_* developer keys + floe_* agent keys). See Credit REST API.

x402 Credit Facilitator:

  • Agents grant a scoped on-chain setOperator permission, then call POST /v1/proxy/fetch with any x402 URL — the facilitator handles borrowing, EIP-3009 signing, and payment automatically.

  • 3-step setup: Create Wallet → Deposit & Delegate → Activate Agent. See Agent Quickstartarrow-up-right.

  • Automated credit health monitoring and graceful wind-down via POST /v1/agents/close or revokeOperator.

  • See x402 Credit Facilitator and Agent Runtime Contract for the full API.

Smart Contract Upgrade #12 (Operator Delegation):

  • setOperator / revokeOperator / getOperatorPermission — scoped, revocable delegation with borrowLimit, maxRateBps, expiry, and onBehalfOfRestriction.

  • All constraints re-validated at every borrow match — the facilitator provably cannot exceed the agent's bounds.

  • Proxy address unchanged: 0x17946cD3e180f82e632805e5549EC913330Bb175. See Contract Addresses.

Security:

  • SSRF hardening on outbound proxy requests.

  • Proxy request rate limiting and domain allowlisting.

  • See Error Codes and Environment Variables for operational reference.

AgentKit SDK Updates:

hashtag
v1.3.0 — AgentKit, Flash Loans & Safe Support (March 2026)

AgentKit Integration:

  • floe-agent (npm) / floe-agentkit-actions (PyPI) — 36 AI agent actions for Floe via Coinbase AgentKitarrow-up-right. Supports Vercel AI SDK, LangChain, OpenAI Agents SDK, and MCP server.

  • floe-agent CLI — interactive terminal agent for testing all 36 actions without framework code.

  • Flash Loan and Deploy actions included.

Flash Loans:

  • Uncollateralized loans borrowed and repaid within a single transaction via flashLoan().

  • FlashArbReceiver — deployable contract for executing flash arbitrage through Aerodrome DEX on Base.

  • Pre-flight checks for fee, liquidity, circuit breaker, and router availability.

Credit Scores:

  • Cred Protocolarrow-up-right integration — on-chain credit scores displayed as radar charts and tier badges (Excellent/Good/Fair/New).

Safe / Multisig Support:

  • Floe loads natively inside the Safe{Wallet} App Store. Automatic detection via RainbowKit, forced on-chain tx mode (no EIP-712 signing).

Smart Contract Updates:

  • Configurable grace period after loan expiry before liquidation.

  • Minimum interest floor for lenders on short-duration loans.

  • Duration ranges (min/max) instead of single values for improved matching.

hashtag
v1.2.0 — Smart Contract Hardening (February 2026)

  • Telegram Bot — LendrBot available on Telegram.

  • X/Twitter Notifications — intent summaries and post-match alerts.

  • Farcaster Mini App.

  • DefiLlama TVL tracking.

hashtag
v1.1.0 — Intent Creation Overhaul (February 2026)

  • Preset templates (Conservative, Balanced, Aggressive) for lending and borrowing.

  • Real-time risk preview panel with LTV risk levels and liquidation warnings.

  • Duration bucket selector (1W, 1M, 3M, 6M, 1Y).

  • Redesigned loan cards with LTV donut gauge.

  • 4 active markets: USDC/WETH, USDC/cbBTC, USDT/WETH, USDT/cbBTC.

hashtag
v1.0.0 — Mainnet Launch (January 2025)

  • Intent-based P2P lending on Base Mainnet.

  • USDC/WETH market with dual-oracle price feeds (Chainlink + Pyth).

  • Circuit breaker protection, solver-based matching, liquidation with 5% bonus.

  • LendingIntentMatcher proxy: 0x17946cD3e180f82e632805e5549EC913330Bb175.

  • Web app at app.floelabs.xyzarrow-up-right.

hashtag
Protocol Parameters

Parameter
Value
Description

minLtvGapBps

800 (8%)

Min gap between origination & liquidation LTV

withdrawalBufferBps

300 (3%)

Buffer below liquidation for withdrawals

stalenessTimeout

3,600 sec

Oracle staleness threshold

maxDeviationBps

1,500 (15%)

Max price deviation before circuit breaker

sequencerGracePeriod

3,600 sec

Post-recovery wait period

liquidationBonus

500 (5%)

Bonus for liquidators

minGracePeriod

86,400 sec

Min grace period after loan expiry (1 day)

maxGracePeriod

2,592,000 sec

Max grace period (30 days)

hashtag
Security

hashtag
Bug Bounty

  • Program active at security@floelabs.xyz

  • Critical: Up to $50,000

  • High: Up to $20,000

  • Medium: Up to $5,000

  • Low: Up to $1,000

hashtag
Reporting Issues

  1. Security issues: security@floelabs.xyz (do not disclose publicly)

  2. General bugs: GitHub Issues or Discord

  3. Feature requests: Discord #suggestions

hashtag
Links

PreviousGlossaryNextFlash Loans

Last updated