Getting Started with Infura's Ethereum API [A Step by Step Guide]

Infura provides developers and enterprises with simple, reliable access to Web3 tools and infrastructure. Our Ethereum and IPFS API suite serves and supports thousands of decentralized applications every day.

In this post, we’ll walk you through how to get started with Infura so you can connect to the Ethereum blockchain and start building awesome software.

We’ll cover:

Signing up for an account
Creating a new project
Security features like whitelisting and how to protect your project credentials
Making requests.

Step One: Register

The first thing to do is to head to Infura.io and create an account. Protecting user information is one of our core values. That’s why you’ll notice that the only bit of info required to register an account is an email address. You can add your name if you like, but it’s not necessary.

Infura only uses your email address to communicate with you about critical service updates that may impact your usage. New product and features releases, offers, industry, company and event news are communicated through our newsletter. Our newsletter is opt-in so we strongly recommend you subscribe to keep up to-date with the latest Infura product news, tips and tricks.

You need to verify your email address, by clicking the link sent to your inbox, before your account can be activated.

Step Two: Create a Project

Once verified, you’ll be taken to your Infura Dashboard. From here, you can take a product tour (strongly recommend), or create your first project:

You can test your new API credentials by sending a curl request inside terminal or command prompt where your Project ID is appended to the end of your request URL:

https://<network>.infura.io/v3/YOUR-PROJECT-ID

Be sure to replace YOUR-PROJECT-ID with a Project ID from your Infura Dashboard and <network> with the network you are trying to connect to, e.g. mainnet or rinkeby. You can view a full list of networks we support here, or check your project settings.

Authenticating using a Project ID and Project Secret

In addition to a Project ID, each project also has a Project Secret for sending requests. As additional protection for your request traffic, you should use HTTP Basic Authentication to securely send requests with your project secret.

Your Project ID doesn’t need to be kept secret, but, your Project Secret should never be human readable in your application — be sure to keep it confidential! If you are concerned that your ID and secret have been compromised, you can easily create a new project and generate a new pair.

Remember, never expose your PROJECT_SECRET in client-side code such as Javascript imported into a webpage or iOS or Android apps. Use the other options for securing public project IDs instead:

curl — user :YOUR-PROJECT-SECRET \
https://<network>.infura.io/v3/YOUR-PROJECT-ID

Step Three: Copy Your Keys and Select Your Endpoint

Next, select which Ethereum endpoint you want to connect to. This could be the Ethereum mainnet, or it could be to a test network, like Kovan, Goerli, Rinkeby, or Ropsten.

Copy the endpoint URL. This is the URL that your app will use to send API requests from your decentralized applications. It is your main connection point to the Ethereum blockchain.

Using these endpoint URLs removes any need for you to set up and run your own infrastructure.

Step Four: Control How Your API Can Be Used — Enable Your Custom Security Settings.

If you are sending API requests from a web browser, or other client-side application that does not have the ability to secure your Project Secret, whitelisting can be used to prevent a third party from using your Project ID on another website.

Understanding Whitelist Behavior

If a project has no whitelists enabled, any request will be accepted;
As soon as any whitelist entries are added, all requests must pass each whitelist type;
Each whitelist type is “AND”ed together;
Multiple entries of the same type are “OR”ed;
Protecting a client-side credential can be simple or complex depending on the scenario. Use the whitelist features that best fit your application. Don’t just use the User-Agent or Origin whitelist, use both whenever possible.

Step Five: You’re Set Up— Now, Start Making Requests!

Start interacting with Ethereum data by sending data requests using HTTP or Websockets. To get you started, here’s an example of how to send requests for two common use cases — and the data that will be returned returned:

(i) Retrieve the Current Block Number

Below is a simple command you can run to retrieve the current block number. Remember, you need to use your own unique project ID in place of YOUR-PROJECT-ID:

curl https://mainnet.infura.io/v3/YOUR-PROJECT-ID \
-X POST \
-H “Content-Type: application/json” \
-d ‘{“jsonrpc”:”2.0",”method”:”eth_blockNumber”,”params”: [],”id”:1}

The response you receive back will look like this:

{“jsonrpc”:”2.0",”id”:1,”result”:”0x8d8abf”}

The data returned is in hexadecimal, prefixed with 0x. If you convert 8d8abf to decimal, using a tool like RapidTables, the resulting number is 9276095 representing the block number at the time the query was made.

(ii) Check the Ether Balance For a Given Contract

For this example, we’ll need a contract address to check. Let’s pick TheDAO Withdraw contract: 0xBf4eD7b27F1d666546E30D74d50d173d20bca754

curl https://mainnet.infura.io/v3/YOUR-PROJECT-ID \
-X POST \
-H “Content-Type: application/json” \
-d ‘{“jsonrpc”:”2.0",”method”:”eth_getBalance”,”params”: [“0xBf4eD7b27F1d666546E30D74d50d173d20bca754”, “latest”],”id”:1}’

The response you receive back will look like this:

{“jsonrpc”:”2.0",”id”:1,”result”:”0x1887fd3c2b394d81a33d”}

Once again, by converting the hexadecimal 1887fd3c2b394d81a33d to decimal, you’ll get back 115845353546137586475837. What does this string of numbers mean? This the balance of Ether in that contract in wei. You may want to convert this to Ether. If 1 Ether equals 10¹⁸ wei, simply move the decimal eighteen places to the left. Voila! Now we know there’s a balance of 115845.353546137586475837 Ether in TheDAO Withdraw contract.

There are more sample queries in our documentation, so head to https://infura.io/docs and try them out.

Step Six: Use the Infura Dashboard to Gain Insight Into Your Application

Now that you’ve started issuing requests, your dashboard will start populating with insights on performance and API usage.

Jump into your dashboard regularly to drill down into specific request methods, bandwidth usage and most active usage times to optimize your app and better understand your users.