Build with Pocket

Quickstart

Pocket Network Portal endpoints are designed to be compatible in any web3 library or environment that access an RPC URL. This means that getting up and started is a simple 2 step process.

Step 1 – Get an Endpoint

The first step to getting started using Pocket Network is to sign up for the Portal, create an application, and get the endpoint for the chain(s) that you need access to.

Head over to the Get an Endpoint page for full details of this process.

Step 2 – Plug it into your Application

There are many different reasons why a developer would need to access a blockchain in their application. Your Portal URL is designed to work directly in some of the existing frameworks and libraries that different developers would be interacting with.

UI and Interface Developers

If you’re building an interface to blockchain applications, a collection of examples of how to use your Portal endpoint is available under Popular Libraries.

Smart Contract Developers

If you’re a smart contract developer needing access to live chains in your development environment, a collection of how to of examples of how to leverage your Portal endpoint can be found under Smart Contract Environments.

Interacting Directly with the Chain

If you’re looking to access blockchain data directly, but aren’t using a framework or library, head over to our interactive API Documentation to see how to interact directly with the underlying blockchain API, either directly in your browser with your Portal endpoint, or through the code samples provided for each of the different supported requests.

Get An Endpoint

In order to take advantage of Pocket’s network of thousands of decentralized nodes, you need to get an endpoint that you can use in your application.

You can create your own using the Pocket Portal.

The Pocket Portal is a gateway to a decentralized RPC network, where developers can create (“mint”) blockchain network endpoints for use in their applications. Portal users can also monitor network performance and configure custom security features around their endpoint.

In this way, the Pocket Portal provides similar functionality to more centralized API services, all while retaining the decentralization that Pocket Network is built on.

The Portal has two usage tiers, an Always Free tier that allows for up to 250,000 relays per day, and a Pay As You Go tier that also offers relays beyond that with a nominal fee.

Jump to:

Create an account
Explore the Portal
Test Your Endpoint

Create an account

To use the Pocket Portal, you must first create an account.

The Portal accepts two different methods of account creation and authentication:

Using your email address
Using your GitHub account

Warning

Once you create an account with one login method, you can’t switch to another method with that account, so make sure you choose the method that works best for you.

From the main Pocket Portal page:

Click Get Started at the bottom of the page. Alternatively, you can click Sign Up at the top right.
On the sign up page, enter your email address and a password. When done, click Continue.
Info
Your password must contain at least 8 characters, and at least 3 of the following character types: lower case letters, upper case letters, numbers, and special characters. If your password does not meet these requirements, the failing criteria will be displayed on the screen.
On the next screen, click Accept to authorize the app to allow access to your newly-created account.
You will then be sent a verification email to the address you entered above. Open this email, and click Confirm Email Address.
Info
When you click this link, you will be taken to the main Portal homepage. You will know that verification succeeded because you will receive a subsequent email confirming your registration.
You can now log in. Click the Log In button and you will be taken to the Login page. Enter your credentials as previously given and click Continue.

Continue below at Explore the Portal.

You can also log in the Portal using your existing GitHub account.

Click Get Started at the bottom of the page. Alternatively, you can click Sign Up at the top right.
Click Continue with GitHub.
On the next screen, click Accept to authorize the app to allow access to your GitHub account.
You will then be logged in and taken to the Network Overview page. You will also receive an email confirming your registration.

Continue below at Explore the Portal.

Explore the Portal

Once you’ve logged in, you’ll be taken to the Network page (also known as the Dashboard).

Network Summary

In this section, you’ll see all the important parts of the Pocket network: how many nodes are staked on the network, blockchains supported, number of relays served over time, latest block details, and much more.

To search for a specific chain and its details, the Available Networks section has a search box where you can type in the name of a chain you would like to see.

Apps and Endpoints

Your Portal account is organized into Applications (Apps), which are subdivided into Endpoints.

An App is a project or container that allows you to view network throughput and relays across multiple blockchains.
An Endpoint is the RPC URL that connects to a specific blockchain via Pocket’s network of decentralized nodes.

Your account can contain a maximum of two Apps, and each App can contain any number of Endpoints for any number of chains.

Usage Tiers

Pocket Portal allows you to have 250,000 blockchain relays per App daily, absolutely free.

For many users, this is probably all you need. For others, especially with production-ready apps, you may wish to have more usage on-demand.

With both of these cases in mind, Pocket Portal offers two tiers: Always Free and Pay As You Go.

Always Free: Provides 250,000 relays per App per day, through any combination of Endpoints.
Pay As You Go: Also provides the same 250,000 relays per App per day, through any combination of Endpoints. However, should your App request more than this in a day, you will be charged a per-relay usage fee.

You can always switch between tiers. If you are hitting your limits in the Always Free tier, you can Upgrade to the Pay As You Go tier. And if you don’t need or want the extra daily relays, you can downgrade to the Always Free tier.

Info

The Portal has overflow protection in case an App in the Always Free plan accidentally goes over 250,000 relays in a day. All surplus relays are served by our backup infrastructure, ensuring no service interruptions. This is only a temporary measure, so the app owner should upgrade the plan to Pay As You Go or contact sales for an enterprise plan.

If your App doesn’t hit the 250,000 relay cap, the tiers are identical; the only difference is that you will be asked to enter your payment information during the creation of the App (or during the Upgrade process).

Info

If you created an App prior to September 27, 2022, it will show up as “Legacy” instead of “Always Free” or “Pay As You Go”. Your App will be grandfathered into a legacy free tier for a limited time, with no rate limiting put in place.

Calculate usage

On the page where you create your app, there is a pricing calculator that allows you to estimate what the costs could be, given a certain number of relays per day.

For example, 500,000 daily relays at a price per relay of $0.000007456 would cost approximately $56.68 per month.

Info

This is necessarily an estimate, as the way the relays vary over a period of time will affect the total cost. To take a simple example, if 1,000,000 relays were to happen in a single day, there would be a charge for 750,000 relays, but if those 1,000,000 relays were spread out equally over four days, there wouldn’t be a charge, due to the 250,000 free relays per day.

If your App uses less than 250,000 relays per day, across all of your Endpoints, you will not be charged.

Create an App

When you first create an account on the Pocket Portal, you will have no Apps, so the first thing to do is to create one.

Click the Apps link on the top bar to go to its section. This is where you manage your Apps.

To create a new App:

Click Create New Application.
Enter a name for your App (which can be anything, as it’s just a container).
Choose your tier: Pay As You Go or Always Free.
Info
See the section on Usage Tiers for the differences between the two tiers.
When finished, click Create App.
If you chose the Always Free tier, you will be taken to the App overview section.
If you chose the Pay As You Go tier, you will be redirected to a checkout page. Enter your payment information and click Subscribe. You will then be taken to the App overview section.

Congratulations! You have created an App and are ready to start connecting to Pocket’s network of decentralized infrastructure. You can find a list of your Apps by clicking the Apps link on the top bar.

App Overview

Clicking one of your Apps in the list takes you to the App Overview page.

The App Overview displays all the metrics associated with your App. The charts will start being populated as soon as you start submitting requests through an Endpoint associated with your App.

You’ll see key details:

Endpoints: List of Endpoints associated with the App, from the list of supported blockchains. Any number of Endpoints can be created for a given App.
Portal ID: Unique identifier for the App. This string is included as part of the URL for each Endpoint.
Secret Key: Security feature for Apps. If “Private Secret Key Required” is selected in the Security section, the Secret Key will need to be sent along with the request using HTTP Basic Authentication.
Public Key: Unique identifier for a given App that will allow you to inspect the App on-chain.

Manage Endpoints

Every App gets created with Ethereum Mainnet as its single Endpoint.

To add a new Endpoint to your App:

Click Add New in the Endpoint section.
In the box that appears, click the name of the chain you wish to connect to. You may also use the search box to narrow down the choices.

The new Endpoint will then appear in the list.

To delete an Endpoint, click the trash can icon next to the Endpoint.

All Endpoints have a similar URL structure:

https://<NETWORK>.gateway.pokt.network/v1/lb/<YOUR-PORTAL-ID>

The network prefix. You can find them on the list of supported blockchains in the column Portal API Prefix. For example, Ethereum Mainnet is eth-mainnet.
The main URL (gateway.pokt.network/v1/)
If it’s a load-balanced endpoint (and most of them are), it will also have the /lb/ prefix.
The Portal ID, which is unique to your App.

Requests

The Requests page for a given App shows the success and error rates for your App across all of your Endpoints. It will also log the errors found as part of the requests made.

Security

The Security page for a given App allows you to better secure your Endpoints and your associated dApps. We recommend setting some or all of these for your specific App to reduce the risk of undesired activity.

Private Secret Key Required: When this is enabled every request sent to an Endpoint has to be sent using HTTP Basic Authentication with your Secret Key to be accepted. (When using curl, you would add --user :YOUR-SECRET-KEY.)
Approved Chains: Limits the Endpoints to be used only with specific chains. This list need not be exactly the same as the list of Endpoints on the App Overview page.
Whitelist User-Agents: Limits requests to only the HTTP User-Agents specified. If a User-Agent not on the list attempts to connect to the Endpoint, the request will be blocked. If nothing is specified, all User-Agents will be accepted.
Whitelist Origins: Limits requests to only the HTTP Origins specified. If an Origin not on the list is used in a request to the Endpoint, the request will be blocked. If nothing is specified, all Origins will be accepted. Wildcards are supported.
Whitelist Contracts: Limits requests to the smart contract addresses specified. If the Endpoint is used in a contract address not specified in the list, the request will be denied. Each contract address listed is chain-specific. If nothing is specified, all contract addresses on all chains will be valid.
Whitelist Methods: Limits requests to use specific RPC methods. If a request uses a method not on this list, the request will be denied. Each method listed is chain-specific. If nothing is specified, all methods on all chains will be valid.

When making changes, be sure to click Save at the bottom of the page.

Notifications

Info

This section is only visible for Apps on the Always Free tier. If your App is on the Pay As You Go tier, you will see the Plan Details page instead.

On this page, you can set up email alerts to be warned when you are approaching your relay limits.

There are four thresholds available for alerts. Each can be individually toggled:

25% of 250,000 relays per day
50% of 250,000 relays per day
75% of 250,000 relays per day
100% of 250,000 relays per day

You can also see your weekly bandwidth usage on this page, including average, maximum, and minimum values.

When making any changes, be sure to click Save Changes.

Plan Details

Info

This section is only visible for Apps on the Pay As You Go tier. If your App is on the Always Free tier, you will see the Notifications page instead.

This page shows you details about your subscription, including your total relays on the billing period, and your latest invoice. You can view and download your latest invoice, as well as manage your plan.

Test your Endpoint

Once you’ve set up your Apps and Endpoints to your liking, you can send requests to them to test that your settings are correct.

For EVM-based chains such as Ethereum, you can refer to the official JSON-RPC specification. Below is an example of such a request using cURL.

curl -X POST \\
-H "Content-Type: application/json" \\
--data '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}' \\
"https://<NETWORK>.gateway.pokt.network/v1/lb/<YOUR-PORTAL-ID>"

curl -X POST ^
-H "Content-Type: application/json" ^
--data "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"eth_blockNumber\", \"params\": []}" ^
"https://<NETWORK>.gateway.pokt.network/v1/lb/<YOUR-PORTAL-ID>"

Pocket also maintains API docs that include various methods to test out your specific Endpoint, by generating and sending requests to that Endpoint.

To test out your Endpoint, navigate to the API Docs page for the Pocket blockchain, and click any of the queries on the left sidebar. For example, a simple request is to check the block height.

Once on the page, enter your Portal ID in the box on the right and then click Send API Request. The response will be shown below.

There are also code samples for various platforms available in the Request Sample box. You can copy these code samples and use them in your own test applications.

Popular Libraries

.NET – Web3

Overview

Web3 is a simple wrapper for interacting with JSON RPC, and is provided by Nethereum, a suite of .NET Ethereum development tools.

Resources

Basic Usage

Supported Chains

using System;
using System.Threading.Tasks;
using Nethereum.Web3;

namespace NethereumSample
{
    class Program
    {
        static void Main(string[] args)
        {
            GetAccountBalance().Wait();
            Console.ReadLine();
        }

        static async Task GetAccountBalance()
        {
            var URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>";
            var ACCCOUNT = "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae";
            var web3 = new Web3(URL);
            var balance = await web3.Eth.GetBalance.SendRequestAsync(ACCOUNT);
            Console.WriteLine($"Balance in Wei: {balance.Value}");

            var etherAmount = Web3.Convert.FromWei(balance.Value);
            Console.WriteLine($"Balance in Ether: {etherAmount}");
        }
    }
}

Go – ethclient

Overview

The ethclient package built to enable remote communication directly to an ethereum mode, including RPC access over HTTP.

Resources

Documentation

Basic Usage

Supported Chains

package main

import (
    "context"
    "fmt"
    "log"
    "math"
    "math/big"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/ethclient"
)

func main() {
    url :=
    client, err := ethclient.Dial("https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>")
    if err != nil {
        log.Fatal(err)
    }

    account := common.HexToAddress("0x71c7656ec7ab88b098defb751b7401b5f6d8976f")
    balance, err := client.BalanceAt(context.Background(), account, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(balance)

    blockNumber := big.NewInt(5532993)
    balanceAt, err := client.BalanceAt(context.Background(), account, blockNumber)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(balanceAt)

    fbalance := new(big.Float)
    fbalance.SetString(balanceAt.String())
    ethValue := new(big.Float).Quo(fbalance, big.NewFloat(math.Pow10(18)))
    fmt.Println(ethValue) // 25.729324269165216041

    pendingBalance, err := client.PendingBalanceAt(context.Background(), account)
    fmt.Println(pendingBalance)
}

Java – Web3j

Overview

Web3j is a Java and Android library for interacting with ethereum nodes.

Resources

Basic Usage

Supported Chains

import org.web3j.protocol.Web3j;
import org.web3j.utils.Convert;
import org.web3j.protocol.http.HttpService;
import org.web3j.protocol.core.DefaultBlockParameterName;
import org.web3j.protocol.core.methods.response.EthGetBalance;
import java.math.BigInteger;
import java.math.BigDecimal;
import java.io.IOException;

class Main
{
    public Main(){}

    public void GetAccountBalance()
    {
        String URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>";
        String ACCOUNT = "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae";
       Web3j web3j = Web3j.build(new HttpService(URL));

       try {
          EthGetBalance ethGetBalance = web3j.ethGetBalance(ACCOUNT,               DefaultBlockParameterName.LATEST).send();

          BigInteger balance = ethGetBalance.getBalance();

          System.out.println("Balance in Wei: " + balance);

          BigDecimal etherAmount = Convert.fromWei(balance.toString(),             Convert.Unit.ETHER);
          System.out.println("Balance in Ether :" + etherAmount);
       }
       catch(IOException e) {
          // Code to handle an IOException here
           return;
         }


    }

    public static void main(String[] args)
    {
        //GetAccountBalance();
    }
}

JavaScript – ethers.js

Overview

Ethers is a JavaScript library for interacting with Ethereum and the ecosystem that's been built on it, including first class support for Pocket Network.

Resources

Basic Usage

Supported Chains

import { ethers } from "ethers";

const POCKET_URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>"

const provider = new ethers.providers.JsonRpcProvider(POCKET_URL);

const blockNumber = await provider.getBlockNumber();

console.log(blockNumber);

JavaScript – web3.js

Overview

web3.js is a collection of JavaScript libraries that enable communicating with Ethereum nodes.

Resources

Basic Usage

Supported Chains

import { Web3 } from "web3";

const POCKET_URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>"

const provider = new Web3(POCKET_URL);

const blockNumber = await provider.eth.getBlockNumber();

console.log(blockNumber);

Python – Web3.py

Overview

Web3.py is a Python library for interacting with Ethereum nodes; it originally began as a port of web3.js, but has evolved to better serve the needs of Python developers.

Resources

Basic Usage

Supported Chains

from web3 import Web3

POCKET_URL = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>"

provider = Web3(Web3.HTTPProvider(POCKET_URL))

print(provider.blockNumber)

Rust – web3

Overview

web3-rust is a rust implementation of web3.js.

Resources

Repository

Basic Usage

Supported Chains

async fn main() -> web3::Result<()> {
    let url = "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>";
    let transport = web3::transports::Http::new(url)?;
    let web3 = web3::Web3::new(transport);

    let account = "00a329c0648769a73afac7f9381e08fb43dbea72";

    println!("Calling balance.");
    let balance = web3.eth().balance(account, None).await?;
    println!("Balance of {:?}: {}", account, balance);

    Ok(())
}

Swift – web3.swift

Overview

web3.swift is a Swift API that supports a subset of the Ethereum JSON RPC, as well as additional methods to ease ENS, ERC20, and ERC721 interaction.

Resources

Repository

Basic Usage

Supported Chains

import web3

guard let clientUrl = URL(string: "https://<PREFIX>.gateway.pokt.network/v1/lb/<PORTAL-ID>") else { return }
let client = EthereumClient(url: clientUrl)

client.eth_gasPrice { (error, currentPrice) in
    print("The current gas price is \(currentPrice)")
}

Smart Contract Environments

Solidity & Vyper – Apeworx

Overview

Apeworx is an Ethereum development framework targeted at Python developers, data scientists, and security professionals.

Resources

Documentation

Basic Usage

Supported Chains

Apeworx allows you to specify multiple ecosystems, networks, and providers. Apeworx specifically has configurations in ape-config.yaml for connecting to live network nodes; it’s here where you would want to specify the Portal Endpoint. While this section is called geth, it’s not limited to just geth nodes.

For our example, let’s specify 2 ecosystems, Ethereum and Polygon, both including testnets.

geth:
  ethereum:
    mainnet:
      uri: https://eth-mainnet.gateway.pokt.network/v1/lb/<PORTAL-ID>
    goerli:
      uri: https://eth-goerli.gateway.pokt.network/v1/lb/<PORTAL-ID>
  polygon:
    mainnet:
      uri: https://poly-mainnet.gateway.pokt.network/v1/lb/<PORTAL-ID>
    mumbai:
      uri: https://poly-mumbai.gateway.pokt.network/v1/lb/<PORTAL-ID>

You would then be able to connect your Apeworx console to Goerli through Pocket Network as follows:

ape console --network ethereum:goerli:geth

Solidity & Vyper – Brownie

Overview

Brownie is a Python-based development and testing framework for EVM compiled smart contracts.

Resources

Documentation

Basic Usage

Supported Chains

Brownie handles all of its network management via the CLI, meaning that you’ll have to specify networks individually as commands.

For example, this is how you would add Goerli.

brownie networks add Ethereum goerli host=https://eth-goerli.gateway.pokt.network/v1/lb/<PORTAL-ID> chainId=5

Note, the chainId is not related to the Pocket Relay Chain ID, but rather, the value returned by eth_chainId.

From here, you’d be able to connect your brownie console to this network by running:

brownie --network goerli

Solidity & Vyper – Hardhat

Overview

Hardhat is a highly extensible and modular TypeScript-based Ethereum development environment, with a mature Solidity debugging experience.

Resources

Documentation

Basic Usage

Supported Chains

Hardhat allows you to configure networks through a networks object exported in the hardhat.config.js file. Here’s an example of adding networks for Ethereum and Polygon, both mainnet and testnet.

require("@nomicfoundation/hardhat-toolbox");

const PORTAL_ID = "<PORTAL-ID>";

// Replace these privates key with your respective account private key
// To export your private key from Metamask, open Metamask and
// go to Account Details > Export Private Key
// Beware: NEVER put real Ether into testing accounts

const MAINNET_PRIVATE_KEY = "YOUR MAINNET PRIVATE KEY";
const GOERLI_PRIVATE_KEY = "YOUR GOERLI PRIVATE KEY";
const POLY_PRIVATE_KEY = "YOUR MAINNET PRIVATE KEY";
const MUMBAI_PRIVATE_KEY = "YOUR MAINNET PRIVATE KEY";

module.exports = {
  solidity: "0.8.9",
  networks: {
    mainnet: {
      url: `https://eth-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [MAINNET_PRIVATE_KEY]
    },
    goerli: {
      url: `https://eth-goerli.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [GOERLI_PRIVATE_KEY]
    },
    polygon: {
      url: `https://poly-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [POLYGON_PRIVATE_KEY]
    },
    mumbai: {
      url: `https://poly-mumbai.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      accounts: [MUMBAI_PRIVATE_KEY]
    }
  }
};

Then, say you wanted to deploy to Goerli, you’d simply run your deployment as follows:

npx hardhat run scripts/deploy.js --network goerli

Solidity & Vyper – Truffle

Overview

Truffle is a JavaScript based EVM development environment, testing framework, and asset pipeline.

Resources

Documentation

Basic Usage

Supported Chains

Truffle allows you to configure networks through a networks object exported in the truffler-.config.js file. Here’s an example of adding networks for Ethereum and Polygon, both mainnet and testnet.

const PORTAL_ID = "<PORTAL-ID>"

module.exports = {
  networks: {
    mainnet: {
      host: `https://eth-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "1",
    },
    goerli: {
      host: `https://eth-goerli.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "5",
    },
    polygon: {
      host: `https://poly-mainnet.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "137",
    },
    mumbai: {
      host: `https://poly-mumbai.gateway.pokt.network/v1/lb/${PORTAL_ID}`,
      port: 80,
      network_id: "80001",
    }
  }
};

Note, the chainId is not related to the Pocket Relay Chain ID, but rather, the value returned by eth_chainId.

From here, you’ll be able to connect your truffle console to Pocket as follows:

truffle console --network mainnet

Build with Pocket

Quickstart

Step 1 – Get an Endpoint

Step 2 – Plug it into your Application

UI and Interface Developers

Smart Contract Developers

Interacting Directly with the Chain

Get An Endpoint

Create an account

Sign up with email

Sign up with GitHub

Explore the Portal

Network Summary

Apps and Endpoints

Usage Tiers

Calculate usage

Create an App

App Overview

Manage Endpoints

Requests

Security

Notifications

Plan Details

Test your Endpoint

More questions?

Popular Libraries

.NET – Web3

Overview

Resources

Basic Usage

Go – ethclient

Overview

Resources

Basic Usage

Java – Web3j

Overview

Resources

Basic Usage

JavaScript – ethers.js

Overview

Resources

Basic Usage

JavaScript – web3.js

Overview

Resources

Basic Usage

Python – Web3.py

Overview

Resources

Basic Usage

Rust – web3

Overview

Resources

Basic Usage

Swift – web3.swift

Overview

Resources

Basic Usage

Smart Contract Environments

Solidity & Vyper – Apeworx

Overview

Resources

Basic Usage

Solidity & Vyper – Brownie

Overview

Resources

Basic Usage

Solidity & Vyper – Hardhat

Overview

Resources

Basic Usage

Solidity & Vyper – Truffle

Overview

Resources

Basic Usage