Blockchain APIs in Web3 Applications
What a blockchain API does in a Web3 app: read chain data, send transactions and receive notifications, and why smart contracts need oracles for off-chain data.
Reviewed by Maurice Sobiera
A blockchain API is a web interface that lets an application read blockchain data and submit transactions without running its own node. In a Web3 application it sits between the user interface and the chain. Smart contracts cannot call web APIs themselves, so data from outside the chain reaches them through oracles.
This article separates the two directions in which APIs and blockchains connect, and explains where each one is used.
What does a blockchain API do in a Web3 application?
A blockchain API gives an application three things: it reads chain data, it submits transactions, and it reports events. Without one, your backend would need to run a node, keep it synced and parse blocks itself.
| Job | Example | How it works |
|---|---|---|
| Read | Balance of an address, transactions in a block | A request to a node or to an API provider |
| Write | Send a token transfer | The transaction is signed with a private key, then broadcast to the network |
| Notify | Tell the backend that a deposit arrived | A webhook, or polling of the node |
Chaingateway is one such API. Its wallet, transfer and webhook endpoints are listed in the OpenAPI file. Webhooks exist for Bitcoin, Ethereum, BNB Smart Chain, Polygon, Arbitrum and Tron. Solana has no webhooks, so a Solana application has to poll.
Why can’t a smart contract call a web API?
A smart contract cannot call a web API because every node must execute it and reach the same result. Ethereum’s documentation states that pulling in outside data would make determinism impossible: a price API could return different values to different nodes, and the nodes would no longer agree on the state of the chain (ethereum.org: oracles).
This is a property of the design. It does not depend on the chain’s language or on any particular API. The consequence is that data must be put on the chain by a transaction before a contract can use it.
How does off-chain data reach a smart contract?
Off-chain data reaches a contract through an oracle. An oracle is an application that sources, verifies and transmits external information to smart contracts. A lending protocol that needs the price of an asset, or a contract that depends on weather or flight data, needs one.
Ethereum’s documentation describes two common designs:
- Publish-subscribe: the oracle publishes a data feed, and contracts read it. This suits data that changes often, such as token prices.
- Request-response: a contract requests specific data, and the oracle answers in a callback. This suits large datasets where a contract needs only a small part. The requester pays for the lookup and for the gas of the callback.
An oracle operated by one party is a single point of failure. If that party fails, is hacked or lies, the contract acts on wrong data. The same documentation describes decentralized oracle services, where several participants agree on the data before it reaches the contract. Decentralization is a spectrum, and you still have to decide how much you trust the oracle you pick.
Which API do you need for which job?
The answer depends on the direction of the data flow.
| Direction | Problem | Tool |
|---|---|---|
| Chain to application | Read balances, send transfers, get deposit notifications | Blockchain API or your own node |
| Outside world to contract | Give a contract a price, a score or a weather value | Oracle |
| Contract to outside world | Trigger an action after an on-chain event | Event logs read by a service, or an oracle |
A payment system uses only the first row. A user pays to an address, a webhook reaches your backend, and your backend credits the account in its own database. No oracle is involved. See blockchain vs database for how to split the work between the chain and your database.
How does an application read events from a contract?
An application reads contract events through logs. When a contract emits an event, the node stores it in the transaction receipt, and the eth_getLogs method of the Ethereum JSON-RPC API, which follows the JSON-RPC 2.0 specification, returns the logs that match a filter. This is the usual way to find token transfers.
A filter for ERC-20 Transfer events of one token, in a block range, looks like this:
{ "jsonrpc": "2.0", "method": "eth_getLogs", "params": [{ "fromBlock": "0x10d4f00", "toBlock": "0x10d4f0a", "address": "0xTokenContract", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }], "id": 1}The first topic is the hash of the event signature Transfer(address,address,uint256). The other topics hold the indexed arguments, here the sender and the recipient. The amount is in the data field of each log, as a hex number.
Block ranges matter. Many providers cap the range or the number of results of one eth_getLogs call, so a scanner has to page through blocks. A blockchain API that decodes these logs for you, or pushes them as webhooks, removes this code. It does not change what the logs mean: a log in a block that is later reorganized disappears with that block.
What are the limits of blockchain APIs?
An API does not change how the chain works. A transaction is only final when the chain says so, and an API can report it as pending or confirmed earlier than that. Treat a deposit as settled only after the finality rules of the chain have passed.
Failed webhook deliveries are not retried automatically. Chaingateway lists them in the failed-notifications endpoint of each chain, for example GET /api/v2/tron/webhooks/notifications/failed, and you re-send them with the retry endpoint. A backend that processes webhooks should also be idempotent, so that a re-sent notification does not credit an account twice.
A hosted API also adds a dependency on the provider. If you need direct protocol access, you can still run a node and talk to it over JSON-RPC.
Ready to build this yourself? Get your API key — 7-day trial, no card required — or see the Blockchain API for the full endpoint reference.