feat: add Floe credit action provider

Adds FloeActionProvider — working capital for AI agents on Base.

Financial independence is the precursor to agent autonomy. Long-running
agents can't do anything meaningful without their own fundable balance
sheet. Floe gives them one.

3,000+ secured working capital lines issued. Zero defaults.

8 actions:
  Read: getMarkets, checkStatus, getBalance, checkHealth
  Write: instantBorrow, repay, grantDelegation, x402Fetch

Deposit USDC, borrow up to 95% as a credit line. Fixed rates, per-loan
isolated escrow, gas-free for delegated agents. Fund with a bank account
or card — no crypto experience needed. Built-in x402 payment proxy.

Includes:
  - Full test suite with mocked wallet and API
  - Example agent (typescript/examples/floe-credit-agent/)
  - Provider README

Network: Base Mainnet
Contract: 0x17946cD3e180f82e632805e5549EC913330Bb175

Author: achris7

typescript/agentkit/src/action-providers/floe/README.md

@@ -0,0 +1,59 @@
+# Floe Action Provider
+
+Financial independence is the precursor to agent autonomy. Long-running agents can't do anything meaningful without their own fundable balance sheet. Floe gives them one.
+
+**3,000+ secured working capital lines issued. Zero defaults.**
+
+Deposit USDC, borrow up to 95% as a credit line. Fixed rates, per-loan isolated escrow, gas-free. Fund with a bank account or card — no crypto experience needed.
+
+## Actions
+
+| Action | Type | Description |
+|--------|------|-------------|
+| `getMarkets` | Read | List available lending markets |
+| `instantBorrow` | Write | Deposit USDC, borrow up to 95% working capital — auto-selects best lender |
+| `repay` | Write | Repay a loan (deposit returns automatically) |
+| `checkStatus` | Read | Loan health, balance, accrued interest, time to expiry |
+| `getBalance` | Read | Credit balance for facilitator-delegated agents |
+| `checkHealth` | Read | On-chain LTV and liquidation risk |
+| `grantDelegation` | Write | Delegate credit to Floe facilitator for gas-free x402 payments (one-time) |
+| `x402Fetch` | Write | Call any x402 API — Floe handles payment automatically |
+
+## Setup
+
+```typescript
+import { AgentKit } from "@coinbase/agentkit";
+import { FloeActionProvider } from "@coinbase/agentkit";
+
+const agentkit = await AgentKit.from({
+  walletProvider,
+  actionProviders: [new FloeActionProvider()],
+});
+
+// Deposit 10,000 USDC → get 9,500 USDC credit line
+const loan = await agentkit.run("instantBorrow", {
+  borrowAmount: "9500",
+  collateralAmount: "10000",
+  maxInterestRateBps: "800",
+  duration: "1209600",
+});
+```
+
+## Why agents need credit
+
+100M+ x402 machine payments since May 2025. 100,000+ agents with onchain identity. Zero credit outstanding to any of them.
+
+Every economy runs on credit. Agents don't have FICO — but they have something better: deterministic cashflows and verifiable execution history. Floe is the credit bureau and capital rail for AI agents.
+
+## Network
+
+- **Base Mainnet** — Coinbase's L2, built for payments
+- **Contract:** [`0x17946cD3e180f82e632805e5549EC913330Bb175`](https://basescan.org/address/0x17946cD3e180f82e632805e5549EC913330Bb175)
+
+## Links
+
+- [Docs](https://floe-labs.gitbook.io/docs)
+- [Bank Account → First API Call](https://floe-labs.gitbook.io/docs/agents/fiat-to-x402) — fund with fiat, no crypto needed
+- [Full npm package (45 actions)](https://www.npmjs.com/package/floe-agent)
+- [Dashboard](https://dev-dashboard.floelabs.xyz)
+- [Website](https://floelabs.xyz)

typescript/agentkit/src/action-providers/floe/constants.ts

@@ -0,0 +1,86 @@
+import { type Address } from "viem";
+
+export const SUPPORTED_NETWORKS = ["base-mainnet"];
+
+export const LENDING_MATCHER_ADDRESSES: Record<string, Address> = {
+  "base-mainnet": "0x17946cD3e180f82e632805e5549EC913330Bb175",
+};
+
+export const FACILITATOR_ADDRESSES: Record<string, Address> = {
+  "base-mainnet": "0x58EDdE022FFDAD3Fb0Fb0E7D51eb05AaF66a31f1",
+};
+
+export const FACILITATOR_API = "https://credit-api.floelabs.xyz";
+
+export const TOKEN_ADDRESSES: Record<string, Record<string, Address>> = {
+  "base-mainnet": {
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    weth: "0x4200000000000000000000000000000000000006",
+    cbbtc: "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf",
+  },
+};
+
+export const USDC_DECIMALS = 6;
+
+export const LENDING_MATCHER_ABI = [
+  {
+    inputs: [
+      { name: "operator", type: "address" },
+      { name: "borrowLimit", type: "uint256" },
+      { name: "maxRateBps", type: "uint256" },
+      { name: "expiry", type: "uint256" },
+      { name: "onBehalfOfRestriction", type: "address" },
+    ],
+    name: "setOperator",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "agent", type: "address" },
+      { name: "operator", type: "address" },
+    ],
+    name: "getOperatorPermission",
+    outputs: [
+      { name: "approved", type: "bool" },
+      { name: "borrowLimit", type: "uint256" },
+      { name: "borrowed", type: "uint256" },
+      { name: "maxRateBps", type: "uint256" },
+      { name: "expiry", type: "uint256" },
+      { name: "onBehalfOfRestriction", type: "address" },
+    ],
+    stateMutability: "view",
+    type: "function",
+  },
+] as const;
+
+export const ERC20_ABI = [
+  {
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    name: "approve",
+    outputs: [{ name: "", type: "bool" }],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "account", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+    ],
+    name: "allowance",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function",
+  },
+] as const;

typescript/agentkit/src/action-providers/floe/floeActionProvider.test.ts

@@ -0,0 +1,224 @@
+import { encodeFunctionData, parseUnits, type Hex } from "viem";
+import { EvmWalletProvider } from "../../wallet-providers/evmWalletProvider";
+import { FloeActionProvider } from "./floeActionProvider";
+import { LENDING_MATCHER_ADDRESSES, LENDING_MATCHER_ABI, USDC_DECIMALS } from "./constants";
+import { Network } from "../../network";
+
+describe("Floe Action Provider", () => {
+  const actionProvider = new FloeActionProvider("https://mock-api.test");
+  let mockWallet: jest.Mocked<EvmWalletProvider>;
+
+  const MOCK_NETWORK: Network = { protocolFamily: "evm", networkId: "base-mainnet" };
+  const MOCK_ADDRESS = "0x1234567890abcdef1234567890abcdef12345678";
+  const MOCK_TX_HASH = "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" as Hex;
+  const MOCK_RECEIPT = { status: 1, blockNumber: 123456 };
+  const MOCK_SIGNATURE = "0xmocksignature";
+
+  beforeEach(() => {
+    mockWallet = {
+      getAddress: jest.fn().mockResolvedValue(MOCK_ADDRESS),
+      getNetwork: jest.fn().mockReturnValue(MOCK_NETWORK),
+      sendTransaction: jest.fn().mockResolvedValue(MOCK_TX_HASH),
+      waitForTransactionReceipt: jest.fn().mockResolvedValue(MOCK_RECEIPT),
+      signMessage: jest.fn().mockResolvedValue(MOCK_SIGNATURE),
+      readContract: jest.fn(),
+    } as unknown as jest.Mocked<EvmWalletProvider>;
+
+    global.fetch = jest.fn();
+    jest.clearAllMocks();
+  });
+
+  describe("supportsNetwork", () => {
+    it("returns true for base-mainnet", () => {
+      expect(actionProvider.supportsNetwork(MOCK_NETWORK)).toBe(true);
+    });
+
+    it("returns false for base-sepolia", () => {
+      expect(
+        actionProvider.supportsNetwork({ protocolFamily: "evm", networkId: "base-sepolia" }),
+      ).toBe(false);
+    });
+
+    it("returns false for unsupported networks", () => {
+      expect(
+        actionProvider.supportsNetwork({ protocolFamily: "evm", networkId: "ethereum-mainnet" }),
+      ).toBe(false);
+    });
+
+    it("returns false for non-evm networks", () => {
+      expect(
+        actionProvider.supportsNetwork({ protocolFamily: "solana", networkId: "base-mainnet" }),
+      ).toBe(false);
+    });
+  });
+
+  describe("getMarkets", () => {
+    it("returns formatted market data", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          markets: [
+            { collateralSymbol: "USDC", loanSymbol: "USDC" },
+          ],
+        }),
+      });
+
+      const result = await actionProvider.getMarkets(mockWallet, {});
+      expect(result).toContain("Floe Lending Markets");
+      expect(result).toContain("USDC/USDC");
+    });
+
+    it("handles empty markets", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ markets: [] }),
+      });
+
+      const result = await actionProvider.getMarkets(mockWallet, {});
+      expect(result).toContain("No active markets");
+    });
+
+    it("handles API errors", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+      });
+
+      const result = await actionProvider.getMarkets(mockWallet, {});
+      expect(result).toContain("Error fetching markets");
+    });
+  });
+
+  describe("instantBorrow", () => {
+    it("calls the correct API with auth headers", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ loanId: "42" }),
+      });
+
+      const result = await actionProvider.instantBorrow(mockWallet, {
+        borrowAmount: "1000",
+        collateralAmount: "10000",
+        maxInterestRateBps: "800",
+        duration: "1209600",
+      });
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://mock-api.test/v1/credit/instant-borrow",
+        expect.objectContaining({ method: "POST" }),
+      );
+      expect(result).toContain("Loan Created");
+      expect(result).toContain("1000 USDC");
+      expect(result).toContain("10000 USDC");
+    });
+
+    it("handles no liquidity", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        json: async () => ({ error: "no_liquidity" }),
+      });
+
+      const result = await actionProvider.instantBorrow(mockWallet, {
+        borrowAmount: "1000",
+        collateralAmount: "10000",
+        maxInterestRateBps: "800",
+        duration: "1209600",
+      });
+
+      expect(result).toContain("No lenders available");
+    });
+  });
+
+  describe("grantDelegation", () => {
+    it("encodes setOperator correctly and sends transaction", async () => {
+      const result = await actionProvider.grantDelegation(mockWallet, {
+        facilitatorAddress: "0x58EDdE022FFDAD3Fb0Fb0E7D51eb05AaF66a31f1",
+        borrowLimit: "10000",
+        maxRateBps: "1500",
+        expiryDays: "90",
+      });
+
+      expect(mockWallet.sendTransaction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: LENDING_MATCHER_ADDRESSES["base-mainnet"],
+        }),
+      );
+      expect(result).toContain("Credit Delegation Granted");
+      expect(result).toContain("10000 USDC");
+      expect(result).toContain("15.00% APR");
+      expect(result).toContain("90 days");
+    });
+
+    it("rejects unsupported networks", async () => {
+      mockWallet.getNetwork.mockReturnValue({
+        protocolFamily: "evm",
+        networkId: "ethereum-mainnet",
+      } as Network);
+
+      const result = await actionProvider.grantDelegation(mockWallet, {
+        facilitatorAddress: "0x58EDdE022FFDAD3Fb0Fb0E7D51eb05AaF66a31f1",
+        borrowLimit: "10000",
+        maxRateBps: "1500",
+        expiryDays: "90",
+      });
+
+      expect(result).toContain("not supported");
+    });
+  });
+
+  describe("checkStatus", () => {
+    it("returns formatted loan status", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          remainingPrincipal: "500000000",
+          accruedInterest: "12500000",
+          interestRateBps: 800,
+          status: "active",
+          timeToExpiry: "10 days",
+        }),
+      });
+
+      const result = await actionProvider.checkStatus(mockWallet, { loanId: "42" });
+      expect(result).toContain("Loan #42 Status");
+      expect(result).toContain("8.00% APR");
+      expect(result).toContain("active");
+    });
+  });
+
+  describe("x402Fetch", () => {
+    it("calls proxy endpoint with auth headers", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        headers: new Map([["payment-response", "0xtxhash"]]),
+        text: async () => '{"data": "premium content"}',
+      });
+
+      const result = await actionProvider.x402Fetch(mockWallet, {
+        url: "https://api.example.com/data",
+      });
+
+      expect(global.fetch).toHaveBeenCalledWith(
+        "https://mock-api.test/v1/proxy/fetch",
+        expect.objectContaining({ method: "POST" }),
+      );
+      expect(result).toContain("x402 Response");
+    });
+
+    it("handles insufficient balance", async () => {
+      (global.fetch as jest.Mock).mockResolvedValueOnce({
+        ok: false,
+        status: 402,
+        json: async () => ({ error: "insufficient_balance", available: "100", required: "500" }),
+      });
+
+      const result = await actionProvider.x402Fetch(mockWallet, {
+        url: "https://api.example.com/data",
+      });
+
+      expect(result).toContain("Insufficient credit balance");
+    });
+  });
+});