Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/nodeflare-action-provider.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@coinbase/agentkit": minor
---

Added NodeFlare action provider for reading on-chain data (block number, native and ERC-20 balances, token metadata, gas price, transactions, and multi-chain balances) across 17 EVM chains through NodeFlare's public gateway, addressed by chain slug, name, or chain ID.
1 change: 1 addition & 0 deletions typescript/agentkit/src/action-providers/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ export * from "./messari";
export * from "./pyth";
export * from "./moonwell";
export * from "./morpho";
export * from "./nodeflare";
export * from "./opensea";
export * from "./spl";
export * from "./superfluid";
Expand Down
48 changes: 48 additions & 0 deletions typescript/agentkit/src/action-providers/nodeflare/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# NodeFlare Action Provider

This directory contains the **NodeflareActionProvider** implementation, which provides actions to read on-chain data across **17 EVM chains** through [NodeFlare](https://nodeflare.app)'s public RPC gateway — Ethereum, Base, BNB Chain, Arbitrum, Optimism, Avalanche, HyperEVM, Polygon, and young chains like Robinhood Chain, Ink, Zircuit, BOB and Soneium.

Unlike a wallet-bound provider, every action takes an explicit `chain` argument (slug, name, **or** chain ID), so an agent can query any supported chain without configuring a separate RPC per chain. All actions are read-only and keyless — the injected wallet provider is not used.

## Directory Structure

```
nodeflare/
├── nodeflareActionProvider.ts # Main provider with NodeFlare read actions
├── nodeflareActionProvider.test.ts # Test file for NodeFlare provider
├── schemas.ts # Action schemas
├── index.ts # Main exports
└── README.md # This file
```

## Actions

- `get_supported_chains`: List the EVM chains NodeFlare serves, with chain IDs and native currencies
- `get_block_number`: Get the latest block number on any supported chain
- `get_native_balance`: Get the native gas-token balance of an address (ETH, BNB, POL, HYPE, …), human-readable
- `get_erc20_balance`: Read an ERC-20 token balance for a holder, human-readable using the token's decimals
- `get_token_metadata`: Read ERC-20 token metadata (name, symbol, decimals, total supply)
- `get_gas_price`: Get the current gas price on a chain, in gwei
- `get_transaction`: Look up a transaction by hash (from, to, value, block)
- `get_multichain_balances`: Native + ERC-20 balances for one address across many of the 17 chains in one call (incl. young chains)

Every action's `chain` argument accepts a slug (`base`), a name (`ethereum`, `bsc`), or a numeric chain ID (`8453`).

## Adding New Actions

To add new NodeFlare actions:

1. Define your action schema in `schemas.ts`
2. Implement the action in `nodeflareActionProvider.ts`
3. Add tests in `nodeflareActionProvider.test.ts`

## Network Support

The provider reads any of NodeFlare's 17 supported EVM chains, selected per-action via the `chain` argument, so it is available regardless of the network the host agent's wallet is configured for. For the full list and endpoints, see the [NodeFlare chains directory](https://nodeflare.app/chains).

## Notes

- **No API key required.** Actions use NodeFlare's free public read tier. Heavy methods (`eth_getLogs`, trace) are not exposed here; for those, use the [NodeFlare MCP server](https://github.com/Nodeflare-app/nodeflare-mcp) with a free API key.
- Read-only: this provider does not send transactions or touch the agent's wallet.

For more information, visit the [NodeFlare docs for AI agents](https://nodeflare.app/agents).
2 changes: 2 additions & 0 deletions typescript/agentkit/src/action-providers/nodeflare/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
export * from "./nodeflareActionProvider";
export * from "./schemas";
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
import { nodeflareActionProvider, NodeflareActionProvider } from "./nodeflareActionProvider";

/**
* Build a fetch mock that returns the given JSON body with a 200 status.
*
* @param body - The JSON body to resolve.
* @returns A jest mock installed on global.fetch.
*/
function mockFetch(body: unknown) {
return jest.spyOn(global, "fetch").mockResolvedValue({
ok: true,
json: async () => body,
} as Response);
}

describe("NodeflareActionProvider", () => {
let provider: NodeflareActionProvider;

beforeEach(() => {
provider = nodeflareActionProvider();
jest.restoreAllMocks();
});

afterEach(() => {
jest.clearAllMocks();
});

it("supports every network (chain is an explicit argument)", () => {
expect(provider.supportsNetwork()).toBe(true);
});

describe("getSupportedChains", () => {
it("lists the supported chains", async () => {
const response = await provider.getSupportedChains();
expect(response).toContain("NodeFlare serves");
expect(response).toContain("eth (chainId 1, ETH)");
expect(response).toContain("base (chainId 8453, ETH)");
});
});

describe("getBlockNumber", () => {
it("returns the latest block in decimal and hex", async () => {
mockFetch({ jsonrpc: "2.0", id: 1, result: "0x2a" });
const response = await provider.getBlockNumber({ chain: "ethereum" });
expect(response).toContain("Ethereum latest block: 42 (0x2a)");
});

it("resolves a numeric chain ID", async () => {
mockFetch({ jsonrpc: "2.0", id: 1, result: "0x1" });
const response = await provider.getBlockNumber({ chain: "8453" });
expect(response).toContain("Base latest block:");
});

it("returns a helpful error for an unknown chain", async () => {
const response = await provider.getBlockNumber({ chain: "notachain" });
expect(response).toContain("unknown chain 'notachain'");
});
});

describe("getNativeBalance", () => {
it("returns a human-readable native balance", async () => {
mockFetch({ jsonrpc: "2.0", id: 1, result: "0x0de0b6b3a7640000" }); // 1e18
const response = await provider.getNativeBalance({
chain: "eth",
address: "0x0000000000000000000000000000000000000000",
});
expect(response).toContain("1 ETH");
expect(response).toContain("Ethereum");
});
});

describe("getGasPrice", () => {
it("returns the gas price in gwei", async () => {
mockFetch({ jsonrpc: "2.0", id: 1, result: "0x3b9aca00" }); // 1e9 wei = 1 gwei
const response = await provider.getGasPrice({ chain: "base" });
expect(response).toContain("Base gas price: 1 gwei");
});

it("surfaces a gateway error", async () => {
mockFetch({ error: "rate_limit_exceeded", message: "Public rate limit exceeded." });
const response = await provider.getGasPrice({ chain: "eth" });
expect(response).toContain("Error fetching gas price");
expect(response).toContain("Public rate limit exceeded");
});
});

describe("getMultichainBalances", () => {
it("aggregates balances across chains via the data API", async () => {
mockFetch({ address: "0xabc", chains: [{ chain: "base", chainId: 8453, native: { currency: "ETH", balance: "1.5", wei: "1500000000000000000" }, tokens: [] }] });
const response = await provider.getMultichainBalances({ address: "0xabc", chains: ["base"] });
expect(response).toContain("Multi-chain balances for 0xabc");
expect(response).toContain("\"chain\": \"base\"");
});
});
});
Loading
Loading