Schema Basics

Basics

The core idea of the GraphQL API is to describe available entities and attributes with a schema and let the client decide which parts, elements, and services it needs to perform its operation. Our schema is extensively commented and you should be able to grab the right data just by comparing your needs with the schema. Please let us know if you still miss anything important.

The API server supports introspection. It means that with a competent development tool, you can scan the available structure and build your GraphQL queries with full support of known structures.

Conventions

The API follows these conventions and recommendations:

• GraphQL types are capital camelCases.

• Attributes are regular camelCases.

• Function calls are named and managed the same way as attributes.

• Complex input and output values are encapsulated in a type instead of an expanded list.

• Each type, attribute, and function has a comment describing its purpose.

Scalar Values

The API uses several different scalar values besides the default GraphQL set. Most of them encode big values or byte arrays of hashes and addresses. If your client application is built using JavaScript, or TypeScript, you can benefit from using the excellent Ethereum Web3.js library, which can help you deal with the decoding and validating process of most data types used here.

Transaction amounts, account balances, rewards, and basically all amount-related data are transferred as big integers encoded in prefixed hexadecimal format. It represents the smallest indivisible amount of value inside the blockchain, the so-called WEI.

One FTM token contains 10¹⁸ WEIs.

The following scalar values are used by the API:

• Hash is a 32-byte binary string, represented by 0x prefixed hexadecimal number.

• Address is a 20-byte Opera address, represented by 0x prefixed hexadecimal number.

• BigInt is a large integer value. Input is accepted as either a JSON number or a hexadecimal number alternatively prefixed with 0x. Output is 0x prefixed hexadecimal.

• Long is a 64-bit unsigned integer value represented by 0x prefixed hexadecimal number.

• Bytes is an arbitrary length binary string, represented by a 0x-prefixed hexadecimal string. An empty byte string is represented by '0x'.

• Cursor is an unspecified string value representing position in a sequential list of edges. Please see the following section for details about Cursor usage.

Pagination

The API employs cursor-based pagination instead of the commonly used <offset, count> or <from, to> architectures, which rely on numeric offsets from the top of the collection. In our scenario, the top of the collection is constantly changing, making it nearly impossible to track your position with a shifting anchor.

Our approach uses a cursor system, where each member of the collection has a unique identifier called a cursor. To obtain a slice of the collection, you specify the cursor value of a member and the number of neighboring members you need. If you don't specify a cursor, it defaults to either the top or bottom of the collection, determined by the count of neighbors you request.

For example, this query provides 15 consecutive blocks after the one with the cursor "0x134b7":

query BlocksList {
    blocks (cursor: "0x134b7", count: 15) {
        totalCount
        pageInfo {
            first
            last
            hasNext
            hasPrevious
        }
        edges {
            cursor
            block {
                hash
                number
                timestamp
                transactionCount
            }
        }
    }
}

If you just want the 10 most recent transactions, you skip the cursor and send the following query:

query TransactionsList {
    transactions (count: 10) {
        totalCount
        pageInfo {
            first
            last
            hasNext
            hasPrevious
        }
        edges {
            cursor
            transaction {
                hash
                from
                to
                value
                block {
                    timestamp
                }
            }
        }
    }
}

Please note that each response will contain several important bits of info that will help you navigate through the collection.

First is the pageInfo structure, defined by PageInfo type. It contains the first and last cursor of your current slice so you can use these values and ask for next X edges or previous -X edges.

Also each edge of the list contains not only the desired data element, but also a cursor, which can be used to create a link, if desired, to the same position in the collection regardless of the absolute distance of the element from the top or bottom.