Quick start
Willow RPC implements standard Ethereum JSON-RPC over HTTP, and existing Ethereum libraries work with it without modification. A request requires an API key and an endpoint URL.
-
Create an account. Sign up at dashboard.willow.tech/signup with an email address. No payment card is required. The Free plan includes 10M units a month at 25 requests a second.
-
Create a key on the Keys page. The key is displayed once and should be stored securely. A key consists of
wk_followed by 43 letters and digits. -
Send a request. Append the key to the URL, after the chain ID:
https://api.willow.tech/v1/rpc/{chainId}/{YOUR_KEY}
The following examples read the latest block number on Ethereum (chain ID 1)
and the USDC transfers in the last ten blocks. Set the key as an environment
variable first:
export WILLOW_KEY=wk_...curl -s https://api.willow.tech/v1/rpc/1/$WILLOW_KEY \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'{"id":1,"jsonrpc":"2.0","result":"0x18e8f51"}The logs request, with the block range in hexadecimal:
curl -s https://api.willow.tech/v1/rpc/1/$WILLOW_KEY \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"eth_getLogs","params":[{ "fromBlock":"0x18e8f47", "toBlock":"0x18e8f51", "address":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }]}'import { createPublicClient, http, parseAbiItem } from 'viem';import { mainnet } from 'viem/chains';
const client = createPublicClient({ chain: mainnet, transport: http(`https://api.willow.tech/v1/rpc/1/${process.env.WILLOW_KEY}`),});
const latest = await client.getBlockNumber();const transfers = await client.getLogs({ address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'), fromBlock: latest - 10n, toBlock: latest,});console.log(latest, transfers.length);import { JsonRpcProvider, Network, id } from 'ethers'; // ethers v6
const network = Network.from(1);const provider = new JsonRpcProvider( `https://api.willow.tech/v1/rpc/1/${process.env.WILLOW_KEY}`, network, { staticNetwork: network },);
const latest = await provider.getBlockNumber();const transfers = await provider.getLogs({ address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', topics: [id('Transfer(address,address,uint256)')], fromBlock: latest - 10, toBlock: latest,});console.log(latest, transfers.length);staticNetwork prevents ethers from requesting the chain ID before every call.
import osfrom web3 import Web3
w3 = Web3(Web3.HTTPProvider(f"https://api.willow.tech/v1/rpc/1/{os.environ['WILLOW_KEY']}"))
latest = w3.eth.block_numbertransfers = w3.eth.get_logs({ "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "topics": [Web3.keccak(text="Transfer(address,address,uint256)")], "fromBlock": latest - 10, "toBlock": latest,})print(latest, len(transfers))export WILLOW_URL="https://api.willow.tech/v1/rpc/1/$WILLOW_KEY"
cast block-number --rpc-url "$WILLOW_URL"
cast logs --rpc-url "$WILLOW_URL" --from-block latest --to-block latest \ --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \ 'Transfer(address indexed from, address indexed to, uint256 value)'To use another chain, change the chain ID in the URL and the chain in the library configuration. Every chain is listed in Chains and URLs.
Sending the key in a header
Section titled “Sending the key in a header”To keep the key out of the URL, and therefore out of access logs that store
URLs, omit it from the path and send it in an Authorization: Bearer or
X-API-Key header:
curl -s https://api.willow.tech/v1/rpc/1 \ -H "Authorization: Bearer $WILLOW_KEY" \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'const client = createPublicClient({ chain: mainnet, transport: http('https://api.willow.tech/v1/rpc/1', { fetchOptions: { headers: { Authorization: `Bearer ${process.env.WILLOW_KEY}` } }, }),});import { FetchRequest, JsonRpcProvider, Network } from 'ethers';
const request = new FetchRequest('https://api.willow.tech/v1/rpc/1');request.setHeader('Authorization', `Bearer ${process.env.WILLOW_KEY}`);
const network = Network.from(1);const provider = new JsonRpcProvider(request, network, { staticNetwork: network });w3 = Web3(Web3.HTTPProvider( "https://api.willow.tech/v1/rpc/1", request_kwargs={"headers": {"Authorization": f"Bearer {os.environ['WILLOW_KEY']}"}},))cast accepts the key only in the URL. Use the path form above.
Verifying every response
Section titled “Verifying every response”@willow-network/rpc verifies each response
against Ethereum before the app sees it, so the app doesn’t have to trust
Willow. It replaces the transport or provider, and the rest of the code stays
the same:
npm install @willow-network/rpcimport { createPublicClient } from 'viem';import { mainnet } from 'viem/chains';import { willowTransport } from '@willow-network/rpc/viem';
const client = createPublicClient({ chain: mainnet, transport: willowTransport({ chainId: 1, key: process.env.WILLOW_KEY }),});import { WillowProvider } from '@willow-network/rpc/ethers';
const provider = new WillowProvider({ chainId: 1, key: process.env.WILLOW_KEY });A response that fails verification raises an error instead of reaching the app. Verifying client lists what each method is verified by, and what can’t be verified.
Requesting a proof
Section titled “Requesting a proof”Any eth_getLogs filter can be requested with a proof. The cost is first
obtained from willow_quoteLogsProof, which takes the same filter and is not
charged:
curl -s https://api.willow.tech/v1/rpc/1/$WILLOW_KEY \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"willow_quoteLogsProof","params":[{ "fromBlock":"0x18e8f47", "toBlock":"0x18e8f51", "address":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }]}'The same filter is then sent to willow_getLogsProof. Proofs for blocks that
are already proven are returned immediately. Blocks that are not yet proven are
proven on request, and the response states when to repeat the request. Log
proofs are paid from the plan’s proof credit first, then from the account
balance. The Free plan includes $1 of proof credit a month. Beyond it, add
credit or choose a plan on the Billing
page.
The complete flow is described in Proofs, and verification in
Verifying proofs.
Further reading
Section titled “Further reading”- API keys: per-key limits, rotation, and revocation.
- Methods: the data each method returns.
- Limits and errors: the meaning of each error and the corresponding remedy.
- Usage by key, chain, and day is shown on the Usage page.