What is Crypticorn?

Crypticorn is at the forefront of cutting-edge crypto trading with Machine Learning.

Use this API Client to access valuable data sources, contribute to the Hive AI - a community driven AI Meta Model for predicting the crypto market - and programmatically interact with the entire Crypticorn ecosystem.

Installation

You need Python 3.10-3.14 installed to be able to use this library. It might work with older versions, but we don't test it.

You can install the latest stable version from PyPi:

pip install crypticorn

If you want the latest version, which could be a pre release, run:

pip install --pre crypticorn

You can install extra dependencies grouped in the extras extra. The extra dependencies include heavy libraries like pandas, which is only used in a few custom API operations (see data processing), which preprocess the response data as a pandas Dataframe for convenience.

Structure

Our API is available as both an asynchronous and synchronous Python SDK. The main entry points are:

• AsyncClient - Asynchronous client for async/await usage
• SyncClient - Synchronous client for traditional blocking calls

from crypticorn import AsyncClient, SyncClient

Both clients serve as the central interface for API operations and instantiate multiple API wrappers corresponding to our micro services.

You can either explore each API by clicking through the library or checkout the API Documentation.

Request and response models for API operations should be accessed through the sub package you are using for an operation. All symbols are re-exported at the sub package level for convenience.

Versioning

The SDK major version tracks the highest supported API version. A new API major bump always triggers a new major release of this package. Minor and patch versions only add non-breaking changes. We follow Semantic Versioning.

SDK Version	Auth	Trade	Klines	Metrics	Hive	Dex	Pay	Notification	Indicator
v2.x	v1	v1	-	v1	v1	v1	v1	v1	-
v3.x	v1	v2	v1 (v3.3.0+)	v1	v1	v1	v1	v1	v1 (v3.2.0+)
v4.x	v1	v2	v1	v1	v1	v2	v1	v1	v1

Authentication

To get started, create an API key in your dashboard.

The scopes you can assign, resemble the package structure. The first part defines if the scopes is for reading or writing a ressource, the second matches the API, the third the ROUTER being used. read scopes gives access to GET, write to PUT, PATCH, POST, DELETE endpoints.

There are scopes which don't follow this structure. Those are either scopes that must be purchased (e.g. read:predictions), give access to endpoints existing in all APIs (e.g. read:admin) or provide access to an entire service (e.g. read:sentiment).

Basic Usage

Asynchronous Client

You can use the async client with the context manager protocol...

async with AsyncClient(api_key="your-api-key") as client:
    await client.pay.get_products()

...or without it like this...

client = AsyncClient(api_key="your-api-key")
asyncio.run(client.pay.get_products())
asyncio.run(client.close())

...or this.

client = AsyncClient(api_key="your-api-key")

async def main():
    await client.pay.get_products()

asyncio.run(main())
asyncio.run(client.close())

Synchronous Client

For traditional synchronous usage without async/await, use the SyncClient:

from crypticorn import SyncClient

# With context manager (recommended)
with SyncClient(api_key="your-api-key") as client:
    products = client.pay.get_products()
    status = client.trade.ping()

# Or without context manager
client = SyncClient(api_key="your-api-key")
try:
    products = client.pay.get_products()
    status = client.trade.ping()
finally:
    client.close()  # Manual cleanup required

The sync client provides the same API surface as the async client, but all methods return results directly instead of coroutines. Under the hood, it uses asgiref.async_to_sync to bridge async operations to synchronous calls, ensuring reliable operation without requiring async/await syntax.

Response Types

There are three different available output formats you can choose from:

Serialized Response

You can get fully serialized responses as pydantic models. Using this, you get the full benefits of pydantic's type checking.

# Async client
res = await client.pay.get_products()
# Sync client
res = client.pay.get_products()
print(res)

The output would look like this:

[ProductModel(id='67e8146e7bae32f3838fe36a', name='Awesome Product', price=5.0, scopes=None, duration=30, description='You need to buy this', is_active=True)]

Serialized Response with HTTP Info

# Async client
res = await client.pay.get_products_with_http_info()
# Sync client
res = client.pay.get_products_with_http_info()
print(res)

The output would look like this:

status_code=200 headers={'Date': 'Wed, 09 Apr 2025 19:15:19 GMT', 'Content-Type': 'application/json'} data=[ProductModel(id='67e8146e7bae32f3838fe36a', name='Awesome Product', price=5.0, scopes=None, duration=30, description='You need to buy this', is_active=True)] raw_data=b'[{"id":"67e8146e7bae32f3838fe36a","name":"Awesome Product","price":5.0,"duration":30,"description":"You need to buy this","is_active":true}]'

You can then access the data of the response (as serialized output (1) or as JSON string in bytes (2)) with:

print(res.data)
print(res.raw_data)

On top of that you get some information about the request:

print(res.status_code)
print(res.headers)

JSON Response

You can receive a classical JSON response by suffixing the function name with _without_preload_content

# Async client
response = await client.pay.get_products_without_preload_content()
print(await response.json())

# Sync client - Note: use regular methods instead as response.json() returns a coroutine
response = client.pay.get_products_without_preload_content()

The output would look like this:

[{'id': '67e8146e7bae32f3838fe36a', 'name': 'Awesome Product', 'price': 5.0, 'duration': 30, 'description': 'You need to buy this', 'is_active': True}]

Wrapper Utilities

Our SDK provides a collection of wrapper utilities designed to make interacting with the API more efficient and user-friendly.

Data Preprocessing

Some API operations allow to get the returned data formatted as a pandas Dataframe. These operations are suffixed with _fmt and take the same inputs as the non-formatted function. They live alongside the other functions with the default response types. To use this functionality you have to install pandas, which is available in the extra dependency group.

Data Downloads

This utility allows direct data streaming to your local disk, instead of only returning download links. It is being used in the following functions:

• client.hive.download_data() (overrides the default response)

Advanced Usage

Sub Client Configuration

You can override some configuration for specific services. If you just want to use the API as is, you don't need to configure anything. This might be of use if you are testing a specific API locally.

To override e.g. the host for the Hive client to connect to localhost:8000 instead of the default proxy, you would do:

from crypticorn.hive import Configuration as HiveConfig

# Async client
async with AsyncClient() as client:
    client.configure(config=HiveConfig(host="http://localhost:8000"), service='hive')

# Sync client
with SyncClient() as client:
    client.configure(config=HiveConfig(host="http://localhost:8000"), service='hive')

Session Management

By default, AsyncClient manages a single shared aiohttp.ClientSession for all service wrappers. However, you can pass your own pre-configured aiohttp.ClientSession if you need advanced control — for example, to add retries, custom headers, logging, or mocking behavior.

When you inject a custom session, you are responsible for managing its lifecycle, including closing when you're done.

import aiohttp
from crypticorn import AsyncClient

async def main():
    custom_session = aiohttp.ClientSession()
    async with AsyncClient(api_key="your-key", http_client=custom_session) as client:
        await client.trade.ping()
    await custom_session.close()

If you don’t pass a session, AsyncClient will create and manage one internally. In that case, it will be automatically closed when using async with or when calling await client.close() manually.

Note on Sync Client: The SyncClient uses per-operation sessions (creates and closes a session for each API call) to ensure reliable synchronous behavior. Custom sessions are accepted but not used. This approach prevents event loop conflicts at the cost of slightly higher overhead per operation.

Typing Notes

This client supports both sync and async usage from the same API surface.

Because of this, method return types are annotated as:

Union[T, Awaitable[T]]

If you're using static type checking, you may see type errors due to this. This is intentional and reflects the dual sync/async support. You can safely ignore the union type or use typing.cast to enforce the type. Otherwise, Python itself will do the right thing at runtime.