REST API endpoints that potentially may return an unlimited number of items are paginated.

Requests

In addition to the endpoint-specific parameters, endpoints that return paginated responses accept the following pagination parameters to control the page and number of items per page correspondingly:

The maximum number of items per page is 250.

Responses

Paginated responses contain two additional properties providing information on the total number of items and the total number of pages:

Example

Get the second page of accounts with 25 items per page:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts?page=2&page_size=25' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "account_hash": "37f304a6632b214eacc45b85f6a45759194ea69f6684da0bca42d60e42ac8e12",
      "balance": 3050076259180,
      "main_purse_uref": "uref-692b5b8afcad47b0dee74962540a01ea1402fc0c9c84d9474e5766775373795c-007",
      "public_key": "019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c"
    },
    {
      "account_hash": "7894d8458c82388f6d276c07c1c52033ac37b175fa722b9cc40e7a0157ce17fc",
      "balance": 252442325961483,
      "main_purse_uref": "uref-c4afe0fb020ebcdc940289d759499ff5fb87e999567e4d61d836d70bfad20a55-007",
      "public_key": "0145fb72c75e1b459839555d70356a5e6172e706efa204d86c86050e2f7878960f"
    },
    ...
    {
      "account_hash": "eb108759cf29b5d1ce6a311989890170d94bb98e06e4097e4ee20c18d6bf4f16",
      "balance": 80331298738010,
      "main_purse_uref": "uref-fd73e477cbbeb134ebb7fee8ccb423c8d45c88e23bd82d2d1104fc7f34f3a27b-007",
      "public_key": "0154d4c09bcae885fdd3dc0bf8ac7fa23ae281baf60a5b352b1ff0b505a65e1285"
    }
  ],
  "item_count": 63584,
  "page_count": 2544
}

Traversing results

When making an API request to an endpoint that returns paginated data, you usually don't receive all of the results in a single response. To traverse the data, you need to increment the page number in your requests until you collect all the required items. When doing so, note the rate limits. Setting the number of items per page to its maximum value of 250 will minimize the chances of being rate-limited for most of the use cases.

Note that if new objects are added to the list of items being paginated, the contents of each page will change.

The CSPR.cloud API is exclusively available to registered users. To authorize your API requests, an access token is required. The access tokens identify the API user and their corresponding access tier limitations. Please visit the website to learn about the tiers and to submit an access token request. To learn more about rate limites and quotas please read the documentation page.

Authorization header

The access token should be included in the Authorization header:

To learn how to include the Authorization header in Casper SDKs to access the CSPR.cloud Casper Node please read the page.

Accessing from a browser

At this moment CPSR.cloud provides only the server side integration. By using your access token in a front-end application, you'll expose it to the world.

Reporting

You can request the usage report by sending an email from your registered account to .

CSPR.cloud REST API is an HTTP-based API that dApps can use to programmatically query Casper network data. It has predictable resource-oriented endpoints and uses standard HTTP response codes, authentication, and verbs.

CSPR.cloud Streaming API is WebSocket-based and follows the WebSocket standard conventions.

Base URLs

The APIs can be accessed using the following base URLs

Mainnet

Testnet

Authorization

Rate limits and quotas

Responses

The API sends data in the JSON format. Successful REST API responses contain the data property, which contains the response data:

The Streaming API messages additionally include the action and timestamp properties:

Pagination

Requests that potentially may return an unlimited number of items are paginated. Endpoints that return paginated responses accept the page and limit query parameters to control the page and the number of items per page, correspondingly. Paginated responses contain two additional properties providing information on the total number of items and the total number of pages:

Sorting

Filtering

Optional properties

Errors

Error responses contain the error property with optional code, message, and description properties providing more information about the error that occurred:

Versions

At CSPR.cloud, we distinguish between rate limits and quotas to ensure efficient API management.

Rate limit

We impose a limit on the number of requests per minute. This measure helps manage load and avoid overloading our systems.

Quotas

Quotas control the overall call rates over an extended period, often tied to subscription tiers.

• Long-term Management: Quotas determine the total number of calls that can be made in a set period, like a month.

• Tier-based Access: For example, a free tier might allow 10,000 calls per month, while a premium tier could permit up to 10,000,000 calls in the same timeframe.

Exceeding these limits triggers a 429 error, signaling a rate limit breach.

Free tier limits

The free tier limits are set to ensure that you can test the API and integrate it into your application.

Mainnet

Testnet

Handling limits

To effectively manage your API usage and comply with rate limit or quota, consider the following strategies:

• Implement a Backoff-Retry Strategy: In cases where you encounter a 429 error (rate limit or quota exceeded), it's advisable to implement a backoff-retry strategy. This involves reducing the frequency of your API requests to stay within the allowed limits.

• Monitor API Calls: Utilize logging tools to monitor your application’s API usage. This can help you identify patterns and optimize your request strategy to ensure efficient usage.

• Lazy Loading Technique: To reduce unnecessary API calls, implement lazy loading in your application. Trigger API calls based on user interactions, such as clicking a button or reaching a specific section of a page, to minimize the number of requests.

Adhering to these strategies will help you efficiently manage your API usage within the CSPR.cloud environment.

CSPR.cloud is an enterprise-grade middleware platform aimed to super-charge developers and to be the primary way for dApps to interact with the Casper Network. It provides access to indexed and enriched blockchain data, real-time streaming subscriptions, and access to reliable and maintained Casper Node. The APIs include:

• Indexed and normalized network data

• Integrations with the existing fungible and non-fungible (NFT) token standards, such as , , and

• Support of the existing smart contract-level event standards, such as , which is also natively supported by the

• Relevant off-chain data, such as CSPR rates or

• and more

CSPR.cloud was built with developer experience in mind and expands the Casper Node RPC API with more data points and querying possibilities, which are not available via the native node API. You can check for examples in the section.

Reference

To get familiar with CSPR.cloud, we recommend that you read these documents:

• Learn about the general technical aspects of CSPR.cloud API, and how it works

• Learn how to make your first API request and start your integration with the Casper Network

• Learn about CSPR.cloud API possibilities, which aren't present in the Casper Node RPC API

• Get familiar with the REST API reference to know what endpoints are available

• Get familiar with the Streaming API reference to know what Web Socket subscriptions are available

• Learn how to connect to the private Casper Node powered by CSPR.cloud using the most popular SDKs

Support

Legal

REST and WebSocket API endpoints that return multiple results may provide possibility to filter the data by certain properties. Not all properties can be used as filters. Please check the endpoint documentation to find out what properties are available for filtering.

Requests

To filter the results by a property, the corresponding property should be provided as a query param. Multiply filters can be used in one request to narrow down the data to what fits your dApp use-case. Some filters can accept multiple values separated by a comma.

Example

Filter NFT tokens by owner and contract package:

Most of the REST API endpoints allow optional data to be included in their responses. It could be related entities, derived properties, , or CSPR rates at the moment of the entity creation. Please check the endpoint documentation to find out what optional properties could be included in the responses.

Requests

Optional data can be included using the includes query param that specifies a comma-separated list of all optional data that should be included. The includes query param options can be one of three forms:

Scalar values

To include a scalar value its name should be specified the includes list.

Objects

Similar to scalar values to include an object its name should be specified in the includes list. However, for objects it's possible to specify a subset of fields that should be returned using the object querying syntax, which looks like this:

The request above will return only the name and the branding.logo properties of the account info object

Functions

When the included data requires extra parameters, it is included as a function. The function form provides a possibility to specify the needed input. For example, to include the USD to CSPR rate, the USD currency ID 1 should be passed as a parameter to the rate function, like this:

Examples

Scalar values

Objects

Functions

The rate property of the first result in the response above holds the CSPR rate from May 16th, 2023, and the second result has the rate from November 11th, 2022.

Requests made to our APIs can result in several different error responses. The following document describes error values.

Properties

The Error has the following properties:

Error Types

Example

Rate limiting errors

This tutorial will help you make your first API call to receive a list of NFT tokens in the contract.

Prerequisites

We will use cURL to make API calls. You can install it from the website or by using the package manager of your choice.

Create an access token

Please register on to create a CSPR.cloud access token.

First API call

To fetch the NFT tokens in the contract we'll be using the . The endpoint requires a contract package hash, which we can find on :

What's next

Please proceed with the following documents to get familiar with CSPR.cloud:

CSPR.cloud indexes and normalizes on-chain data to improve developers' experience when building on the Casper Network. Below are examples that demonstrate some of the possibilities CSPR.cloud offers. For the full list, please see the API reference pages.

• Receive related entities in a single response to minimize the number of network requests needed to load the data

• Include CSPR rates that were relevant at the moment of a transfer, contract call, or reward creation

• Include account info information provided by the account owner in the responses that contain account identifiers

• Query granular pieces of the auction data that interest you, like all account delegations or a list of the current era validators

• Query fungible token data relevant to your dApp

• Query NFT movements and ownership from CSPR.cloud while focusing on the core business value of your application

• Check aggregated historical contract costs to provide your users with better pricing

• Translate account hashes to the corresponding public key for accounts that were observed on the network

• Translate account main purses to the account public keys to better trace the fund movements

• Subscribe to contract-level events the contracts from your dApps emit to track and aggregate the off-chain state for a better user experience

CSPR.cloud REST API provides the possibility to include related entities in responses. An entity is called related if its identifier is present among the requested entity's properties. For example, the entity is related to the entity because the latter has a deploy_hash property identifying the deploy that produced the action. Not all related entities can be included in responses; the ones that can are listed in the "Optional properties" section for the corresponding entity or endpoint page.

Related entities are included the same as other , using the includes query param. For the related entity to be added to the response, its name has to be specified in the list of includes.

Including related entities makes it possible to fetch the required data in one request, simplifying the integration and reducing latency, which is especially useful when processing paginated responses. Continuing the and example, one may need to know the deploy caller account when processing the NFT Action data. By including the Deploy object in the NFT Action response, all the required information can be received in just one API call instead of requesting the deploy data for each NFT action in the list:

REST API endpoints that return may provide a possibility to sort the results by one of the result properties. Not all properties can be used for sorting. Please check the endpoint documentation to find out the sorting properties.

Requests

In addition to the endpoint-specific parameters, endpoints that return sorted results accept the following parameters to control the sorting property and the order:

The defaults are different for different endpoints and are provided in the corresponding endpoint documentation.

Example

Get blocks sorted by height from lowest to highest:

CPSR.cloud provides granular access to the auction data, which is more convenient than parsing the results of the state_get_auction_info Casper RPC API method, through the following APIs:

• Get bidder

• Get bidders

• Get validator

• Get validators

• Get account delegations

• Get validator delegations

• Get auction metrics

For example, fetching account delegations can be done with the following API request:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts/018afa98ca4be12d613617f7339a2d576950a2f9a92102ca4d6508ee31b54d2c02/delegations?limit=2&offset=0' \
  -H 'Accept: application/json' \
  -H 'Authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "item_count": 129,
  "page_count": 13,
  "data": [
    {
      "bonding_purse": "uref-0ac1ba0100574729337b63b11e1f933b91d1d0f220823bef502bd8957305976b-007",
      "public_key": "018afa98ca4be12d613617f7339a2d576950a2f9a92102ca4d6508ee31b54d2c02",
      "stake": "55342872342594023",
      "validator_public_key": "017d96b9a63abcb61c870a4f55187a0a7ac24096bdb5fc585c12a686a4d892009e"
    },
    {
      "bonding_purse": "uref-917e1aeba7e7d3a322e89069e88b6e0877a59d781840c0ce8223e990e0342d42-007",
      "public_key": "018afa98ca4be12d613617f7339a2d576950a2f9a92102ca4d6508ee31b54d2c02",
      "stake": "55334239891699578",
      "validator_public_key": "0106ca7c39cd272dbf21a86eeb3b36b7c26e2e9b94af64292419f7862936bca2ca"
    },
    ...
    {
      "bonding_purse": "uref-64b18eba7bea61163415e728cc8aec51208e14c7abf29d1ce4d50d317ca43053-007",
      "public_key": "018afa98ca4be12d613617f7339a2d576950a2f9a92102ca4d6508ee31b54d2c02",
      "stake": "10101529405231091",
      "validator_public_key": "01aea86e5fccdf72daa7c65cc8b3d2ca96a006a0dcd70d3617f85fef00b9d78464"
    }
  ]
}

Fungible tokens are one of the most used abstractions implemented on blockchains. CSPR.cloud allows dApp developers to focus on the core logic of their applications by tracking the token activity on the Casper Network for CEP-18 compatible tokens and providing APIs to query that data. CSPR.cloud provides a possibility to:

• Get list of tokens owned by an account with their balances

• Get list of token owners for a fungible token contract

• Get account token activity

• Get contract token activity

Below is an example, that demonstrated fetching list of tokens owned by an account. Note, that we are including optional data about the contract package using the includes query parameter.

curl -X 'GET' -G \
  'https://api.testnet.cspr.cloud/accounts/013ff7b986fd1ebd176692825035f1fefa20fb89796dc533219ad307e56ed97439/ft-token-ownership' \
  --data-urlencode 'includes=contract_package{name,metadata}' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

"data": [
    {
      "balance": "198689800",
      "contract_package": {
        "metadata": {
          "balances_uref": "uref-75c2ee03c1982fc514336a38271a9748cee0994a11f16f8b750c68f142c8a957-007",
          "decimals": 3,
          "name": "Nexfi App Token",
          "symbol": "NFI",
          "total_supply_uref": "uref-6e641bea3588986637bd7a5bd2b80f141bf79d21a5be54152a6dc9ac6f9b42a4-007"
        },
        "name": "Nexfi App Token"
      },
      "contract_package_hash": "04ff7ad6975508fffb5a2f364323503fb045b6d1eaeb9aeaa7283c046e0b6710",
      "owner_hash": "a3caf9628418b3a35bd4a92d62d35e8a244898cdea26c269bf75a2d82ad221f0"
    },
    {
      "balance": "50",
      "contract_package": {
        "metadata": {
          "balances_uref": "uref-897fd9713fa3f57c741a3488d7c1a8a24ac0a1cb273eb861e03491698b6e198d-007",
          "decimals": 1,
          "name": "MP1",
          "symbol": "MonoPoint",
          "total_supply_uref": "uref-7c05f307f0f1f7d3b47ea207cdad169d03e554007efc8646d40c5e87002d1ae1-007"
        },
        "name": "MP1"
      },
      "contract_package_hash": "0ed344ff11750d965f6188eb6bb62dcabc51b20f3900b3c7d2f19463cda23378",
      "owner_hash": "a3caf9628418b3a35bd4a92d62d35e8a244898cdea26c269bf75a2d82ad221f0"
    },
    {
      "balance": "9970000",
      "contract_package": {
        "metadata": {
          "balances_uref": "uref-1db06ca66b714a032b2da27476ae8574656105565cb4990633049e483bc2e52a-007",
          "decimals": 3,
          "name": "ENFLOW TOKEN",
          "symbol": "ENF",
          "total_supply_uref": "uref-874fd7504edc780853175536c76025697fa5f4223c63d1e47e075cad2eadf592-007"
        },
        "name": "ENFLOW TOKEN"
      },
      "contract_package_hash": "223e8b0e3101a7d7671279a08abd38a86cefd590536d0aaa5a068c2c616e11da",
      "owner_hash": "a3caf9628418b3a35bd4a92d62d35e8a244898cdea26c269bf75a2d82ad221f0"
    }
  ],
  "item_count": 3,
  "page_count": 1
}

Often, when looking at the fiat value of a native token amount, we want it to be converted using the rate that was relevant at the moment when the corresponding action happened. CSPR.cloud REST API provides the possibility to do so when requesting data having the timestamp property and when it's semantically acceptable To learn more, visit the CSPR rate page.

In the example below, we include the USD to CSPR rate in the account delegation rewards response by calling the rate function with the USD currency ID as the argument in the includes query param:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts/019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c/delegation-rewards?includes=rate(1)' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "item_count": 38490,
  "page_count": 3849,
  "data": [
    {
      "amount": "139319",
      "era_id": 11774,
      "public_key": "019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c",
      "rate": 0.04051209,
      "timestamp": "2023-12-20T12:55:54Z",
      "validator_public_key": "0106ca7c39cd272dbf21a86eeb3b36b7c26e2e9b94af64292419f7862936bca2ca"
    },
    {
      "amount": "186761050",
      "era_id": 11774,
      "public_key": "019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c",
      "rate": 0.04051209,
      "timestamp": "2023-12-20T12:55:54Z",
      "validator_public_key": "017d96b9a63abcb61c870a4f55187a0a7ac24096bdb5fc585c12a686a4d892009e"
    },
    ...
    {
      "amount": "139010",
      "era_id": 11771,
      "public_key": "019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c",
      "rate": 0.0403257,
      "timestamp": "2023-12-20T06:55:27Z",
      "validator_public_key": "0106ca7c39cd272dbf21a86eeb3b36b7c26e2e9b94af64292419f7862936bca2ca"
    }
  ]
}

Non-fungible tokens, or NFTs, became one of the most popular use cases in the current blockchain world. CSPR.cloud keeps track of all NFT contracts compatible with the CEP-47 and CEP-78 NFT standards on the Casper Network. CSPR.cloud provides a possibility to:

• Get list of NFTs owned by an account

• Get list of NFTs minted within a contract

• Get list of NFTs owners for a contract

• Get account NFT activity

• Get contract NFT activity

• and more

Moreover, CSPR.cloud not only tracks on-chain NFT data but also fetches the off-chain metadata for you, which can be particularly slow when the metadata is stored on IPFS. Below is an example that demonstrated fetching NFT tokens for the CasperPunks contracts, which is a CEP-78 smart NFT contract that stores the token metadata on IPFS:

curl -X 'GET' \
  'https://api.cspr.cloud/contract-packages/ad0cd4ef3cfd9e7222706786e51773af771f063ecce4606282999a7a6d6ac495/nft-tokens' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "contract_package_hash": "ad0cd4ef3cfd9e7222706786e51773af771f063ecce4606282999a7a6d6ac495",
      "is_burned": false,
      "offchain_metadata": {
        "attributes": [
          {
            "trait_type": "background",
            "value": "Red"
          },
          {
            "trait_type": "body",
            "value": "Grey"
          },
          {
            "trait_type": "eyes",
            "value": "Narrow"
          },
          {
            "trait_type": "hat",
            "value": "tophat"
          },
          {
            "trait_type": "mouth",
            "value": "StacheBrown"
          }
        ],
        "compiler": "HashLips Art Engine",
        "date": 1682468152509,
        "description": "The first generation of generative CasperPunks",
        "dna": "5dd6a50e43d44cda7af7d50c7d314af724c2851d",
        "edition": 1,
        "image": "https://api-box.casperpunks.io/metadata/images/1.png",
        "name": "Casper Punks Gen 1 #1"
      },
      "offchain_metadata_status": 2,
      "onchain_metadata": {
        "checksum": "",
        "name": "CasperPunks Gen1",
        "symbol": "CP-GEN1",
        "token_uri": "https://api-box.casperpunks.io/metadata/1"
      },
      "owner_hash": "909ce489ea31a76c8f3ca97364b209b942d023a1a0447dc63263444c1566338a",
      "owner_type": 0,
      "timestamp": "2023-05-23T06:38:53Z",
      "token_id": "1",
      "token_standard_id": 2,
      "tracking_id": 19236
    },
    {
      "contract_package_hash": "ad0cd4ef3cfd9e7222706786e51773af771f063ecce4606282999a7a6d6ac495",
      "is_burned": false,
      "offchain_metadata": {
        "attributes": [
          {
            "trait_type": "background",
            "value": "Purple"
          },
          {
            "trait_type": "body",
            "value": "Grey"
          },
          {
            "trait_type": "eyes",
            "value": "Bulging"
          },
          {
            "trait_type": "hat",
            "value": "PinkMohawk"
          },
          {
            "trait_type": "mouth",
            "value": "Patch"
          }
        ],
        "compiler": "HashLips Art Engine",
        "date": 1682468131158,
        "description": "The first generation of generative CasperPunks",
        "dna": "0de5f3c56c496630c56d0b78739c69a68cbe2824",
        "edition": 10,
        "image": "https://api-box.casperpunks.io/metadata/images/10.png",
        "name": "Casper Punks Gen 1 #10"
      },
      "offchain_metadata_status": 2,
      "onchain_metadata": {
        "checksum": "",
        "name": "CasperPunks Gen1",
        "symbol": "CP-GEN1",
        "token_uri": "https://api-box.casperpunks.io/metadata/10"
      },
      "owner_hash": "6d230cf0b8f2a1aae9b88108f483e66c83a301f59b2c8118e0c7765081e36fe9",
      "owner_type": 0,
      "timestamp": "2023-05-24T14:52:46Z",
      "token_id": "10",
      "token_standard_id": 2,
      "tracking_id": 19247
    },
    ...
    {
      "contract_package_hash": "ad0cd4ef3cfd9e7222706786e51773af771f063ecce4606282999a7a6d6ac495",
      "is_burned": false,
      "offchain_metadata": {
        "attributes": [
          {
            "trait_type": "background",
            "value": "Mint"
          },
          {
            "trait_type": "body",
            "value": "Grey"
          },
          {
            "trait_type": "eyes",
            "value": "Frown"
          },
          {
            "trait_type": "hat",
            "value": "beanie"
          },
          {
            "trait_type": "mouth",
            "value": "Laugh"
          }
        ],
        "compiler": "HashLips Art Engine",
        "date": 1682468103314,
        "description": "The first generation of generative CasperPunks",
        "dna": "1df66a2d43f0de7784136685eb8f85531e53d7d1",
        "edition": 1006,
        "image": "https://api-box.casperpunks.io/metadata/images/1006.png",
        "name": "Casper Punks Gen 1 #1006"
      },
      "offchain_metadata_status": 2,
      "onchain_metadata": {
        "checksum": "",
        "name": "CasperPunks Gen1",
        "symbol": "CP-GEN1",
        "token_uri": "https://api-box.casperpunks.io/metadata/1006"
      },
      "owner_hash": "96609d29c02388c81b6b1bd08feef31d3f3f1331ae39c0ad4f921e43c14d5393",
      "owner_type": 1,
      "timestamp": "2023-05-25T02:24:28Z",
      "token_id": "1006",
      "token_standard_id": 2,
      "tracking_id": 20245
    }
  ],
  "item_count": 2166,
  "page_count": 217
}

Note the offchain_metadata property, which contains the off-chain token metadata.

Accounts on Casper Mainnet and Testnet networks have the possibility to self-identify themselves in a decentralized with the Casper Account Info Standard smart contract. Many validators and contract owner accounts provide information about themselves to increase trust on the network.

CSPR.cloud REST API allows including account information to simplify the integration with the standard for dApps developers. Typically, account info standard data can be included in responses that contain account identifiers like account hashes or public keys.

In the example below, we'll include validator account info data in the account delegations API response. To demonstrate the possibility of filtering included object data, we'll request only the owner name and logo properties of the account info object.

curl -X 'GET' -G \
  'https://api.testnet.cspr.cloud/accounts/018df66cb0257dd378d1944d665ea001518419408d55db740a9bb1a262093cefd9/delegations' \
  --data-urlencode 'includes=validator_account_info{info{owner{name,branding{logo}}}}' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "bonding_purse": "uref-845ca8130882c27ee0da81252ed0deb7787796a3868df4b771e0518383d89a4b-007",
      "public_key": "018df66cb0257dd378d1944d665ea001518419408d55db740a9bb1a262093cefd9",
      "stake": "235732110487",
      "validator_account_info": null,
      "validator_public_key": "0196948158bf5b35c0c84f680f110b8debaa4e7628e13ba336a95651a214d3b9bd"
    },
    {
      "bonding_purse": "uref-a5bac0a17edeed284a0264f3fbbd189d3c4819f0e788a576792dc028c8476fba-007",
      "public_key": "018df66cb0257dd378d1944d665ea001518419408d55db740a9bb1a262093cefd9",
      "stake": "565388190696",
      "validator_account_info": {
        "info": {
          "owner": {
            "branding": {
              "logo": {
                "png_1024": "",
                "png_256": "https://picsum.photos/256/256",
                "svg": ""
              }
            },
            "name": "ACME"
          }
        }
      },
      "validator_public_key": "0106ca7c39cd272dbf21a86eeb3b36b7c26e2e9b94af64292419f7862936bca2ca"
    }
  ],
  "item_count": 2,
  "page_count": 1
}

While accounts are known to be recognized by their public keys, internally on-chain, they are uniquely identified by fixed-length accounts hashes derived from those public keys. Because of that, in certain contexts, we may know the account hash but not the public key. CSPR.cloud maintains the mapping between account hashes and the corresponding public keys to be able to "de-anonymize" the former when needed by requesting the public key as an optional property.

Let's have a look at the Transfer API, for example. The Transfer object only provides the recipient account hash:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/deploys/6117d9f92a40d3785b53145c68a118cf36b974b2803acf41cffce8630acd769c/transfers' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "amount": "2000000000000",
      "deploy_hash": "6117d9f92a40d3785b53145c68a118cf36b974b2803acf41cffce8630acd769c",
      "from_purse": "uref-72653d09444d0b3bd27372247510e9346c39fa831a89008dd9ce849a7b2c15e2-007",
      "id": 1704899420700,
      "initiator_account_hash": "7dc2bcc676eba6196d16374e1a2dbfa1df336f779854d95a0b4e65de6d593158",
      "timestamp": "2024-01-10T15:10:36Z",
      "to_account_hash": "b85634e0695ac3b6a7792c2009377b4a405118571a9c64ab2c66048250fef36c",
      "to_purse": "uref-7bba21087353cf75a83234b07525efdf33f59a6d71da00021a4bb80b6ace4bd7-004",
      "transform_key": "a1845ce7b2d334c7fd39b6313ebcfe4e8e29889bcdc792f7c67c7ba5360fd220"
    }
  ],
  "item_count": 1,
  "page_count": 1
}

Let's "de-anonymize" the recipient of the transfer above by including the to_public_key optional property:

curl -X 'GET' -G \
  'https://api.testnet.cspr.cloud/deploys/6117d9f92a40d3785b53145c68a118cf36b974b2803acf41cffce8630acd769c/transfers' \
  --data-urlencode 'includes=to_public_key' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "amount": "2000000000000",
      "deploy_hash": "6117d9f92a40d3785b53145c68a118cf36b974b2803acf41cffce8630acd769c",
      "from_purse": "uref-72653d09444d0b3bd27372247510e9346c39fa831a89008dd9ce849a7b2c15e2-007",
      "id": 1704899420700,
      "initiator_account_hash": "7dc2bcc676eba6196d16374e1a2dbfa1df336f779854d95a0b4e65de6d593158",
      "timestamp": "2024-01-10T15:10:36Z",
      "to_account_hash": "b85634e0695ac3b6a7792c2009377b4a405118571a9c64ab2c66048250fef36c",
      "to_public_key": "02027fec2d969dd0779358c40abe2a772f309408348c2a1f413fddfe684a4287ba1a",
      "to_purse": "uref-7bba21087353cf75a83234b07525efdf33f59a6d71da00021a4bb80b6ace4bd7-004",
      "transform_key": "a1845ce7b2d334c7fd39b6313ebcfe4e8e29889bcdc792f7c67c7ba5360fd220"
    }
  ],
  "item_count": 1,
  "page_count": 1
}

Note the to_public_key property that was added in the second response. It contains the public key that corresponds to the account hash specified in to_account_hash. Please check Transfer Optional Properties to learn about all the optional data that can be included in the Transfer API responses.

v1.4.6 (November 6, 2024)

• Added ability to sort FTTokenOwnerships (token holders) by balance

• Added new endpoint GET /daily-staking-rewards/{date}

v1.4.5 (October 22, 2024)

• Added tracking of primary CSPR.name names for the reverse resolution

• Bugfixes

v1.4.2 (August 27, 2024)

• Added rates optional field for FTTokenAction resource

• Bugfixes

v1.4.1 (August 20, 2024)

• Added new endpoint GET /network-stats

• Bugfixes

v1.4.0 (August 19, 2024)

• Added CSPR.name API

• Bugfixes

v1.3.10 (August 8, 2024)

• Bugfixes

v1.3.9 (August 6, 2024)

• Add ability to sort validators by is_identified_account_info and total_stake by default

• Fix sorting and pagination for Accounts API

• Fix total delegation rewards data tracking

v1.3.8 (July 12, 2024)

• Data tracking performance optimizations

v1.3.7 (July 2d, 2024)

• Add deploy optional field for Transfers API

• Add the ability to filter nft-actions and ft-actions streams by deploy_hash for Streaming API

• Fix account_info optional field including logic

v1.3.6 (June 26, 2024)

• Bug fixes

v1.3.5 (June 17, 2024)

• Fix GET /daily-deploy-numbers endpoint

v1.3.4 (June 13, 2024)

• Fix GET /accounts/{account_identifier}/associated-to-accounts returning empty associations

v1.3.3 (June 12, 2024)

• Fix ordering for Contracts API

• Fix Bidders API

• Fix filtering byt caller_public_key for Deploys API

v1.3.2 (June 6, 2024)

• Fix validator_performance optional field including logic

• Fix GET /validators/{public_key}/rewards endpoint

v1.3.1 (June 1, 2024)

• Bug fixes

v1.3.0 (May 30, 2024)

• Add POST /accounts endpoint to request multiple accounts by account_hashes

• Fix Accounts API

• Fix GET /accounts/{account_identifier}/total-delegation-rewards endpoint

v1.2.2 (May 28, 2024)

• Fix tracking balances for Accounts without tracked purse_uref

v1.2.1 (May 23, 2024)

• Add Centralized Account Info API

v1.2.0 (May 20, 2024)

• Add new endpoint GET /account/:public_key/total-delegation-rewards to return total rewards from delegations for a specific account

• Add contract_package optional field to all resources that have contract_package_hash field

• Add from_purse_public_key and to_purse_public_key optional fields for Transfers API endpoints

• Add the ability to filter deploys stream by deploy_hash for Streaming API

• Fix Streaming API intermittent connection terminations

• Fix Accounts API to return account balances properly

v1.1.3 (May 13, 2024)

• Add is_burned filter for NFT tokens API

v1.1.2 (May 9, 2024)

• Fixes for NFT API

• Fixes for FT API

v1.1.1 (April 10, 2024)

• Fixes for NFT API

• Optimise Deploys and Blocks APIs

v1.1.0 (April 29, 2024)

• Added ability to sort data by block ranges

• Bug fixes

v1.0.1 (March 26, 2024)

• Improved stability of Streaming API connections

v1.0.0 (March 12, 2024)

• First release. Welcome, CSPR.cloud! 🎉

This is a full list of the available CSPR.cloud REST API entities. Some of the entities are presented as root-level resources, and some represent related information of the root-level resources and are presented as their edges. The endpoints associated with each entity provide all the relevant data about that entity. Value objects that provide a mapping between identifiers and names aren't listed here and are documented with the corresponding endpoint documentation.

Entities may have relations to other entities. Such relations are exposed by the presence of one entity identifier in the other entity properties. Typically, it means that this identifier can be used as a in the API requests and that the related entity could be included in the responses as an .

Web3 comes with a new storage architecture dApps have to embrace. In traditional Web2 applications, users don't interact with the storage directly. It's typically hidden behind the API layer.

Blockchain is data storage that provides data we can trust, and that trust requires no middleman between the users and the changes in the data. In this setup, dApps have to observe the on-chain activity to display the relevant state to the end users. While this can be done by polling the network state using the or , CSPR.cloud is also prepared to assist dApps developers with observing the on-chain activity with its .

Note the extra property that provides technical information, such as deploy_hash, event_id, and the deploy execution transform_id, which can be used to link the event data to the corresponding deploy properly.

CSPR.cloud REST API provides the possibility to resolve CSPR.name names either directly by calling the or by including CSPR.name names as .

At the moment of writing this page (August 27th, 2024), the CSPR.name is not launched yet. That's why we added a test CSPR.name for the Faucet account to allow developers to implement and test their CSPR.name integration before the launch.

Direct CSPR.name to account hash resolution can be done using the and is recommended for the situations when you receive the name outside CSPR.cloud and want to resolve it to the corresponding account hash:

In situations, when you want to resolve account hashes to the corresponding CSPR.name names, in most of the cases it's possible to do by requesting CSPR.name as in the includes query parameter:

The Account entity represents the account observed in the network activity. For example, when the corresponding public key was passed as a deploy argument. Because of that, an Account may not necessarily have a purse and on-chain balance.

Properties

The Account entity has the following properties:

Example

Optional properties

Depending on the endpoint some of the following optional properties may be included in the Account entity: