transpose-data

Welcome to the Transpose Python SDK

A modern python wrapper for the Transpose API Suite.

Getting an API Key

To obtain a free Transpose API key, sign up on our website. Free tier keys have a rate limit of 1 request per second and 250,000 credits per month. If you need higher rate limits for your project or business, don't hesitate to reach out on our Discord or upgrade your tier directly in the webapp!

Join our Discord to ask technical questions, share what you're building, and chat with others in the community.

Installation

Python 3.8 or higher is recommended

To install the python SDK, you can run the following command:

python3 -m pip install -U transpose-data

---

Documentation

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

Product	Description	Documentation
Block API	The Block API provides endpoints for accessing low-level blockchain data at scale, including accounts, blocks, transactions, internal 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 NFT images, operators, 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
SQL API	The SQL API provides direct SQL access to our entire ecosystem of indexed blockchain data. Paired with our robust indexing pipeline, SQL access gives unlimited flexibility in how you mix, aggregate, and query activity across the blockchain.	SQL API Docs
Endpoint API	The Endpoint API provides customized REST endpoints that you can create, version, and use directly in your production applications.	Endpoint API Docs

SDK Documentation

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

SDK Helpers

stringify_list

Converts a list of strings into a single string, separated by a delimiter.

from transpose.src.util.format import stringify_list

stringify_list(['a', 'b', 'c'], ',')
>>> 'a,b,c'

SDK 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 (DEPRECATED AS OF v3.1.0)

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.

---

SDK Options

The Transpose SDK can be configured to your liking, allowing you to change the default behavior of the SDK.

Updating Chain ID

Updating SDK Working Chain ID

If you want to change the chain ID of your query, you can do so by setting the chain_id or chain properties of the Transpose object. For example, if you want to query the Ethereum mainnet, you can do so by running the following code:

from transpose import Transpose
api = Transpose(api_key="YOUR_API_KEY", chain_id=1)

or

from transpose import Transpose
api = Transpose(api_key="YOUR_API_KEY", chain_id="ethereum")

if you wish to change the chain ID of an existing Transpose object, you can do so by running the following code:

api.set_chain("ethereum")

or

api.set_chain(1)

Currently supported chains

Chain ID	Chain Name
1	Ethereum
137	Polygon

Raw JSON Responses

Opt-in to raw JSON Responses

If you wish to receive responses in JSON format, you can set the `json` parameter to `True` when initializing the SDK. This will return all responses as JSON objects.

Response classes are considered deprecated as of v3.1.0 and will be removed in v4.0.0. JSON responses will become standard in v4.0.0

from transpose_sdk import Transpose
api = Transpose(api_key="YOUR_API_KEY", json=True)

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)

Parameter	Required	Description	Type
endpoint_response	Yes	The called API function, which returns a list of data models.	List
requests_per_second	No	The number of requests per second to make	int
results_to_fetch	No	The number of results to fetch	int

Responses

Code	Title	Model
200	Success	Data Model
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
500	Internal Server Error	Error

Here is an example of how to use bulk_request:

recent_blocks_since = api.bulk_request(api.block.blocks_by_date(added_after='2022-01-01 00:00:00', limit=500))

print(len(recent_blocks_since))

>>> 500

---

SDK Extras

The following methods are available as extras to the Transpose SDK.

You can import extras to your project by using:

from transpose.extras import <MODULE>

Some extras will require additional dependencies to be installed. If you are missing dependencies, the SDK will throw a TransposeDependencyError when you try to import the extra. This error will tell you what dependencies are missing, and give you the exact command to install them:

transpose.src.util.errors.TransposeDependencyError: Missing Dependencies. You can install these via `pip install plotly kaleido`

Plotting

Transpose Plotting Specifications

The SDK natively includes a plotting library which implements plotly. Using it, you can quickly create plots of data obtained through the Transpose API.

For a plotting example, check out the demo file, which will graph the past hour's gas prices in a bar chart.

Usage

You'll first need to install the plotting dependencies using:

pip install plotly kaleido

Instantiating a new plot is as simple as importing the Plot class and instantiating it:

from transpose.extras import Plot
chart = Plot(title="Hourly Gas Prices on Ethereum")

This will return an object on which you can call the following methods:

• Plot.plotly()

  • Returns the current plot as a plotly object. From there, you can further customize the plot.

• Plot.show()

  • Renders the current plot in the browser. This plot is interactive, and can be zoomed and panned.

• Plot.render(path, format)

  • Inputs:
    • path -> The path to render the plot to.
    • format -> The format to render the plot as. Can be either png, html, jpg, etc.

• Plot.add_data(data, type, shape, smoothing)

  • Inputs:

    • data -> The data to add to the plot. Takes the following format:

      {
        "x":       [],                   // List of data
        "y":       [],                   // List of data
        "y_axis":  "Gas Price (Gwei)",   // OPTIONAL: The name of the y-axis
        "x_axis":  "Time",               // OPTIONAL: The name of the x-axis
      }
      

    • type -> OPTIONAL: The method used to render the data to the plot. Can be either line or bar.

    • shape -> OPTIONAL: The shape of the line. Can be either linear, spline, vh, hv, vhv, or hvh.

    • smoothing -> OPTIONAL: The number of points to smooth the data with.

      • For line, this will calculate a moving average of the data with a period of smoothing.
      • For bar, this will group and average the data over smoothing points.

---

Making a Request

To get started and make your first request, make a new Transpose object:

from transpose import Transpose

api = Transpose('transpose_api_key')

From there, you can call endpoints from the api.nft, api.ens, api.token, and api.block subclasses.

Debugging Requests

You can view the raw HTTP requests the SDK is making by setting the debug flag to True when creating a new Transpose object. For example:

from transpose import Transpose

api = Transpose('transpose_api_key', debug=True)

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,
    "meta_block_number":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

• SDK Examples
• Transpose Documentation
• Official Discord Server