Python SDK

Transpose BannerTranspose Banner

Welcome to the Transpose Python SDK

Deployment TestsDeployment TestsPyPI versionPyPI versionInstallationsInstallations

A modern python wrapper for the Transpose API Suite.

Getting an API Key

To obtain a free Open Alpha Transpose API key, sign up on our website. API Keys on the free tier provide up to 100,000 requests per month. Please reach out in our Discord to ask technical questions, share what you're building, and chat with others in the community.

Installation

To install the python SDK, run the following command:

python3 -m pip install -U transpose-data

Documentation

You can find specific documentation on a per-product basis below.

ProductDescriptionDocumentation

Block API
The Block API provides endpoints for accessing low-level blockchain data at scale, including accounts, blocks, transactions, and logs.Block API Docs

ENS API
The ENS API provides endpoints for looking up ENS names (both historical and primary), resolving ENS names and records, and monitoring ENS transfers and sales.ENS API Docs

NFT API
The NFT API provides endpoints for retrieving any collection and NFT in existence, as well as owners, transfers, approvals, and much more (fully supports both ERC-721 and ERC-1155 NFTs).NFT API Docs

Token API
The Token API provides endpoints for retrieving any token, token balance, transfer, and symbol in existence, including full support for native token transfers and balances (fully supports both ERC-20 and ERC-777 tokens).Token API Docs

SDK Concepts

You can learn more about the Transpose SDK and how it works below.

Classes

The Transpose SDK uses custom classes to represent API responses:

Error Classes

SDK Error Class Specifications The SDK uses the following error classes to represent API errors:
  • TransposeBadRequest
    • Represents a 400 Bad Request error from the Transpose API.
  • TransposeRateLimit
    • Represents a 429 Rate Limit error from the Transpose API.
  • TransposeInvalidAPIKey
    • Represents a 401 Unauthorized error from the Transpose API.
  • TransposeInternalServerError
    • Represents a 500 Internal Server Error error from the Transpose API.
  • TransposeResourceNotFound
    • Represents a 404 Not Found error from the Transpose API.

These errors will be raised when the SDK encounters an error from the Transpose API.

Response Classes

Response Class Specifications

The SDK will always return a list of response objects from the Transpose API. For example, calling the ens.records_by_date endpoint will return a list of ENSRecord objects.

These response objects can be accessed in the following ways:

  • ENSRecord[0].ens_name will return the first record's ens_name.
  • ENSRecord[i].ens_name retrieves the ens_name from the i-th response

All response objects can also be accessed as a dictionary by calling .to_dict() on them:

  • ENSRecord[0].to_dict() will return the first record as a dictionary.
  • ENSRecord[i].to_dict() retrieves the i-th record as a dictionary.

Pagination

Pagination with the Transpose SDK.

Transpose endpoints will return a maximum of 500 results in a single query. To return the next page, simply call api.next(). If api.next() returns None, then there are no more pages.

Here is a standard pagination implementation:

while True:
    data = api.next()

    # sleep to avoid rate limits
    time.sleep(1)

    # if there are no more pages, exit loop
    if data is None: break

    # otherwise, print length of data
    else: print(len(data))

Bulk Requests

Bulk requesting data with the Transpose SDK Alongside pagination, we also offer a convenience method for iterating over all pages. This method will handle pagination for you, and will return a list of all results.

Usage:

api.bulk_request(endpoint_response, requests_per_second, results_to_fetch)
ParameterRequiredDescriptionType
endpoint_responseYesThe called API function, which returns a list of data models.List
requests_per_secondNoThe number of requests per second to makeint
results_to_fetchNoThe number of results to fetchint

Responses

CodeTitleModel
200SuccessData Model
400Bad RequestError
403ForbiddenError
404Not FoundError
500Internal Server ErrorError

Here is an example of how to use bulk_request:

all_blocks_by_miner = api.bulk_request(api.block.blocks_by_date(mined_after='2022-01-01 00:00:00', miner='0x00192Fb10dF37c9FB26829eb2CC623cd1BF599E8', limit=500))

print(len(all_blocks_by_miner))

>>> 53046

Simple Demo

To show just how powerful our data is, let's get the last ENS domain that expired. All we need is one API call.

from transpose import Transpose

api = Transpose('transpose_api_key')

# get the most recently expired ENS domain
last_expired = api.ens.records_by_date(type='expiration', order='desc', limit=1)

This returns a list of ENS Records, which includes data which you wouldn't be able to easily get from the ENS protocol.

[
  {
    "ens_name":"game-master-dit-gm.eth",
    "ens_node":"9BFFC8C1EDE1E51E4BAE137FA37A81CC0379FC08123C4AA00A931D0D983956B7",
    "contract_address":"0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85",
    "token_id":75929000750162030430773866845127925090084516346841580577625168871716954805188,
    "seq_id":407909,
    "owner":"0x2aC92629c4E0E5e4868588f87DC4356606a590b6",
    "resolver":"0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
    "resolved_address":"0x2aC92629c4E0E5e4868588f87DC4356606a590b6",
    "registration_timestamp":"2022-01-01T05:00:36Z",
    "expiration_timestamp":"2049-12-31T23:58:12Z",
    "grace_period_ends":"2050-03-31T23:58:12Z",
    "premium_period_ends":"2050-04-21T23:58:12Z",
    "in_grace_period":false,
    "in_premium_period":false,
    "is_expired":false,
    "last_refreshed":"2022-06-01T09:51:23Z"
  }
]

Links