Skip to content

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.

  1. 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.

  2. 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.

  3. 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:

Terminal window
export WILLOW_KEY=wk_...
Terminal window
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:

Terminal window
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"]
}]}'

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.

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:

Terminal window
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":[]}'

@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:

Terminal window
npm install @willow-network/rpc
import { 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 }),
});

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.

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:

Terminal window
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.

  • 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.