Pre-release

This release is a pre-release and may not be stable for production use.

compass_api_sdk

Developer-friendly & type-safe Python SDK specifically catered to leverage compass_api_sdk API.

Summary

Compass API: Compass Labs DeFi API

compass_api_sdk
Development
- Maturity
- Contributions

SDK Installation

The SDK can be installed with uv, pip, or poetry package managers.

uv

uv is a fast Python package installer and resolver, designed as a drop-in replacement for pip and pip-tools. It's recommended for its speed and modern Python tooling capabilities.

uv add git+https://github.com/CompassLabs/mono.git#subdirectory=python-sdk

PIP

PIP is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line.

pip install git+https://github.com/CompassLabs/mono.git#subdirectory=python-sdk

Poetry

Poetry is a modern tool that simplifies dependency management and package publishing by using a single pyproject.toml file to handle project metadata and dependencies.

poetry add git+https://github.com/CompassLabs/mono.git#subdirectory=python-sdk

Shell and script usage with `uv`

You can use this SDK in a Python shell with uv and the uvx command that comes with it like so:

uvx --from compass_api_sdk python

It's also possible to write a standalone Python script without needing to set up a whole project like so:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "compass_api_sdk",
# ]
# ///

from compass_api_sdk import CompassAPI

sdk = CompassAPI(
  # SDK arguments
)

# Rest of script here...

Once that is saved to a file, you can run it with uv run script.py where script.py can be replaced with the actual file name.

IDE Support

PyCharm

Generally, the SDK will work well with most IDEs out of the box. However, when using PyCharm, you can enjoy much better integration with Pydantic by installing an additional plugin.

PyCharm Pydantic Plugin

SDK Example Usage

Example

# Synchronous Example
from compass_api_sdk import CompassAPI, models


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.aave_v3.aave_aave_supported_tokens(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM)

    # Handle response
    print(res)

The same SDK client can also be used to make asynchronous requests by importing asyncio.

# Asynchronous Example
import asyncio
from compass_api_sdk import CompassAPI, models

async def main():

    async with CompassAPI(
        api_key_auth="<YOUR_API_KEY_HERE>",
    ) as compass_api:

        res = await compass_api.aave_v3.aave_aave_supported_tokens_async(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM)

        # Handle response
        print(res)

asyncio.run(main())

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme
`api_key_auth`	apiKey	API key

To authenticate with the API the api_key_auth parameter must be set when initializing the SDK client instance. For example:

from compass_api_sdk import CompassAPI, models


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.aave_v3.aave_aave_supported_tokens(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM)

    # Handle response
    print(res)

Available Resources and Operations

Available methods

AaveV3

aave_aave_supported_tokens - Aave Supported Tokens
aave_rate - Interest Rates
aave_avg_rate - Interest Rates: Time Average
aave_std_rate - Interest Rates: Standard Deviation
aave_reserve_overview - Reserve Overview
aave_token_price - Token Prices
aave_liquidity_change - Liquidity Index
aave_user_position_summary - Positions - Total
aave_user_position_per_token - Positions - per Token
aave_historical_transactions - Historical Transactions
aave_supply - Supply/Lend
aave_borrow - Borrow
aave_repay - Repay Loans
aave_withdraw - Unstake
aave_set_user_emode - Set User eMode

AerodromeSlipstream

aerodrome_slipstream_liquidity_provision_positions - List LP Positions
aerodrome_slipstream_pool_price - Pool Price
aerodrome_slipstream_swap_sell_exactly - Swap - from Specified Amount
aerodrome_slipstream_swap_buy_exactly - Swap - into Specified Amount
aerodrome_slipstream_liquidity_provision_mint - Open a New LP Position
aerodrome_slipstream_liquidity_provision_increase - Increase an LP Position
aerodrome_slipstream_liquidity_provision_withdraw - Withdraw an LP Position

Bridge

cctp_burn - Initiate USDC bridging
cctp_mint - Complete USDC bridging

Credit

credit_positions - List credit positions
credit_balances - Get credit account token balances
credit_looped_positions - List looped (leveraged) credit positions
credit_euler_markets - List curated Euler markets
credit_morpho_markets - List curated Morpho markets
credit_create_account - Create credit account
credit_borrow - Borrow against collateral
credit_loop - Open a leveraged loop
credit_unloop - Unwind a leveraged loop
credit_rebalance - Rebalance the leveraged credit book
credit_transfer - Transfer tokens to/from Credit Account
credit_swap - Swap tokens
credit_repay - Repay debt and withdraw collateral
credit_bundle - Execute multiple credit actions

Earn

earn_positions - List earn positions
earn_positions_all - List earn positions across all chains
earn_vaults - List vaults
earn_aave_markets - List aave markets
earn_pendle_markets - List pendle markets
earn_swap_quote - Quote a swap
earn_balances - Get token balances
earn_create_account - Create earn account
earn_transfer - Transfer tokens to/from account
earn_manage - Manage earn position
earn_swap - Swap tokens
earn_bundle - Execute multiple earn actions

ERC4626Vaults

vaults_vault - Get Vault & User Position
vaults_deposit - Deposit to Vault
vaults_withdraw - Withdraw from Vault

Ethena

ethena_vault - Get Vault & User Position
ethena_deposit - Deposit USDe
ethena_request - Request to Withdraw USDe
ethena_unstake - Unstake USDe

GasSponsorship

gas_sponsorship_prepare - Prepare gas-sponsored transaction
gas_sponsorship_approve_transfer - Approve token transfer

Morpho

morpho_vaults - Get Vaults
morpho_vault - Get Vault & User Position
morpho_markets - Get Markets
morpho_market - Get Market
morpho_market_position - Check Market Position
morpho_user_position - Check User Position
morpho_deposit - Deposit to Vault
morpho_withdraw - Withdraw from Vault
morpho_supply_collateral - Supply Collateral to Market
morpho_withdraw_collateral - Withdraw Collateral from Market
morpho_borrow - Borrow from Market
morpho_repay - Repay to Market

Pendle

pendle_market - Get Market & User Position
pendle_positions - List User's Market Positions
pendle_markets - List Market Data
pendle_pt - Trade Principal Token (PT)
pendle_yt - Trade Yield Token (YT)
pendle_liquidity - Manage Liquidity (LP)
pendle_redeem_yield - Redeem Claimable Yield

PerpetualTrading

perpetual_trading_opportunities - List perpetual trading markets
perpetual_trading_positions - List perpetual trading positions
perpetual_trading_candles - Get OHLCV candles
perpetual_trading_activity - Aggregated Hyperliquid activity for a user
perpetual_trading_deposit - Deposit USDC to perpetual trading account
perpetual_trading_deposit_sponsor_prepare - Build the Bridge2 deposit tx from a signed permit
perpetual_trading_withdraw - Withdraw USDC from perpetual trading account
perpetual_trading_market_order - Place market order
perpetual_trading_limit_order - Place limit order
perpetual_trading_cancel_order - Cancel order
perpetual_trading_execute - Execute signed action
perpetual_trading_approve_builder_fee - Approve builder fee
perpetual_trading_enable_unified_account - Enable unified account mode
perpetual_trading_ensure_leverage - Ensure 1x cross leverage
perpetual_trading_set_leverage - Set leverage (defaults to market maximum)

Sky

sky_position - Check USDS Position
sky_buy - Buy USDS
sky_sell - Sell USDS
sky_deposit - Deposit USDS
sky_withdraw - Withdraw USDS

SmartAccount

smart_account_batched_user_operations - Get Smart Account Batched User Operations

Token

token_price - Token Price
token_balance - Token Balance
token_list - List known tokens
token_transfer - Transfer Tokens
token_wrap_eth - Wrap ETH
token_unwrap_weth - Unwrap WETH

TokenizedAssets

tokenized_assets_markets - List markets
tokenized_assets_markets_symbol_ - Get a market
tokenized_assets_positions - List positions
tokenized_assets_balances - Get token balances
tokenized_assets_order_order_hash_ - Get order status
tokenized_assets_redemptions - List redemption requests
tokenized_assets_create_account - Create account
tokenized_assets_transfer - Transfer tokens to/from account
tokenized_assets_quote - Quote an order
tokenized_assets_order - Build an order
tokenized_assets_order_submit - Submit a signed order
tokenized_assets_order_order_hash_cancel - Cancel an order
tokenized_assets_order_order_hash_charge_fee - Charge a partner fee
tokenized_assets_transact_buy - Buy an RWA yield token
tokenized_assets_transact_sell - Sell an RWA yield token

TransactionBundler

transaction_bundler_authorization - Enable Transaction Bundling
transaction_bundler_execute - Construct Bundled Transaction
transaction_bundler_aave_loop - AAVE Leverage Long/Short

UniswapV3

uniswap_quote_buy_exactly - Get Quote - to Specified Amount
uniswap_quote_sell_exactly - Get quote - From Specified Amount
uniswap_pool_price - Pool Price
uniswap_liquidity_provision_in_range - Check if LP is Active.
uniswap_liquidity_provision_positions - List LP
uniswap_swap_buy_exactly - Buy exact amount
uniswap_swap_sell_exactly - Sell exact amount
uniswap_liquidity_provision_mint - Open a new LP position
uniswap_liquidity_provision_increase - Increase an LP position
uniswap_liquidity_provision_withdraw - Withdraw an LP position

Universal

generic_portfolio - List User Portfolio
generic_supported_chains - List Supported Chains
generic_allowance - Get Allowance
generic_ens - Resolve ENS
generic_allowance_set - Set Allowance

Wildcat

wildcat_market - Get Market & User Position

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a RetryConfig object to the call:

from compass_api_sdk import CompassAPI, models
from compass_api_sdk.utils import BackoffStrategy, RetryConfig


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.aave_v3.aave_aave_supported_tokens(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM,
        RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False))

    # Handle response
    print(res)

If you'd like to override the default retry strategy for all operations that support retries, you can use the retry_config optional parameter when initializing the SDK:

from compass_api_sdk import CompassAPI, models
from compass_api_sdk.utils import BackoffStrategy, RetryConfig


with CompassAPI(
    retry_config=RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False),
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.aave_v3.aave_aave_supported_tokens(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM)

    # Handle response
    print(res)

Error Handling

CompassAPIError is the base class for all HTTP error responses. It has the following properties:

Property	Type	Description
`err.message`	`str`	Error message
`err.status_code`	`int`	HTTP response status code eg `404`
`err.headers`	`httpx.Headers`	HTTP response headers
`err.body`	`str`	HTTP body. Can be empty string if no body is returned.
`err.raw_response`	`httpx.Response`	Raw HTTP response
`err.data`		Optional. Some errors may contain structured data. See Error Classes.

Example

from compass_api_sdk import CompassAPI, errors, models


with CompassAPI(
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:
    res = None
    try:

        res = compass_api.aave_v3.aave_aave_supported_tokens(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM)

        # Handle response
        print(res)


    except errors.CompassAPIError as e:
        # The base class for HTTP error responses
        print(e.message)
        print(e.status_code)
        print(e.body)
        print(e.headers)
        print(e.raw_response)

        # Depending on the method different errors may be thrown
        if isinstance(e, errors.HTTPValidationError):
            print(e.data.detail)  # Optional[List[models.ValidationError]]

Error Classes

Primary errors:

CompassAPIError: The base class for HTTP error responses.
- HTTPValidationError: Validation Error. Status code 422. *

Less common errors (7)

Network errors:

httpx.RequestError: Base class for request errors.
- httpx.ConnectError: HTTP client was unable to make a request to a server.
- httpx.TimeoutException: HTTP request timed out.

Inherit from CompassAPIError:

TokenizedAssetsErrorResponse: Standard error envelope returned by every non-2xx response. Surfaced in OpenAPI responses declarations so SDK consumers can decode failures uniformly without inspecting per-status-code shapes. Applicable to 12 of 140 methods.*
MintPrepareNotFoundResponseError: Response when the burn event has not been found yet. This means the burn transaction hasn't been confirmed on-chain yet, or the user hasn't broadcast the burn transaction. Status code 404. Applicable to 1 of 140 methods.*
ResponseValidationError: Type mismatch between the response data and the expected Pydantic model. Provides access to the Pydantic validation error via the cause attribute.

* Check the method documentation to see if the error is applicable.

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the server_url: str optional parameter when initializing the SDK client instance. For example:

from compass_api_sdk import CompassAPI, models


with CompassAPI(
    server_url="https://api.compasslabs.ai",
    api_key_auth="<YOUR_API_KEY_HERE>",
) as compass_api:

    res = compass_api.aave_v3.aave_aave_supported_tokens(chain=models.V1AaveAaveSupportedTokensChain.ARBITRUM)

    # Handle response
    print(res)

Custom HTTP Client

The Python SDK makes API calls using the httpx HTTP library. In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with your own HTTP client instance. Depending on whether you are using the sync or async version of the SDK, you can pass an instance of HttpClient or AsyncHttpClient respectively, which are Protocol's ensuring that the client has the necessary methods to make API calls. This allows you to wrap the client with your own custom logic, such as adding custom headers, logging, or error handling, or you can just pass an instance of httpx.Client or httpx.AsyncClient directly.

For example, you could specify a header for every request that this sdk makes as follows:

from compass_api_sdk import CompassAPI
import httpx

http_client = httpx.Client(headers={"x-custom-header": "someValue"})
s = CompassAPI(client=http_client)

or you could wrap the client with your own custom logic:

from compass_api_sdk import CompassAPI
from compass_api_sdk.httpclient import AsyncHttpClient
import httpx

class CustomClient(AsyncHttpClient):
    client: AsyncHttpClient

    def __init__(self, client: AsyncHttpClient):
        self.client = client

    async def send(
        self,
        request: httpx.Request,
        *,
        stream: bool = False,
        auth: Union[
            httpx._types.AuthTypes, httpx._client.UseClientDefault, None
        ] = httpx.USE_CLIENT_DEFAULT,
        follow_redirects: Union[
            bool, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
    ) -> httpx.Response:
        request.headers["Client-Level-Header"] = "added by client"

        return await self.client.send(
            request, stream=stream, auth=auth, follow_redirects=follow_redirects
        )

    def build_request(
        self,
        method: str,
        url: httpx._types.URLTypes,
        *,
        content: Optional[httpx._types.RequestContent] = None,
        data: Optional[httpx._types.RequestData] = None,
        files: Optional[httpx._types.RequestFiles] = None,
        json: Optional[Any] = None,
        params: Optional[httpx._types.QueryParamTypes] = None,
        headers: Optional[httpx._types.HeaderTypes] = None,
        cookies: Optional[httpx._types.CookieTypes] = None,
        timeout: Union[
            httpx._types.TimeoutTypes, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
        extensions: Optional[httpx._types.RequestExtensions] = None,
    ) -> httpx.Request:
        return self.client.build_request(
            method,
            url,
            content=content,
            data=data,
            files=files,
            json=json,
            params=params,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            extensions=extensions,
        )

s = CompassAPI(async_client=CustomClient(httpx.AsyncClient()))

httpx2 (Pydantic's httpx fork)

httpx2 is Pydantic's maintained fork of httpx. To run this SDK on httpx2, call alias_httpx() at your program's entry point, before importing the SDK, so every import httpx — including the ones inside the SDK — resolves to httpx2:

import httpx2

httpx2.alias_httpx()

from compass_api_sdk import CompassAPI

s = CompassAPI()

An SDK can also be generated against httpx2 directly, so it depends on the fork instead of httpx, by setting python.httpClientLibrary: httpx2 in gen.yaml.

Resource Management

The CompassAPI class implements the context manager protocol and registers a finalizer function to close the underlying sync and async HTTPX clients it uses under the hood. This will close HTTP connections, release memory and free up other resources held by the SDK. In short-lived Python programs and notebooks that make a few SDK method calls, resource management may not be a concern. However, in longer-lived programs, it is beneficial to create a single SDK instance via a context manager and reuse it across the application.

from compass_api_sdk import CompassAPI
def main():

    with CompassAPI(
        api_key_auth="<YOUR_API_KEY_HERE>",
    ) as compass_api:
        # Rest of application here...


# Or when using async:
async def amain():

    async with CompassAPI(
        api_key_auth="<YOUR_API_KEY_HERE>",
    ) as compass_api:
        # Rest of application here...

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass your own logger class directly into your SDK.

from compass_api_sdk import CompassAPI
import logging

logging.basicConfig(level=logging.DEBUG)
s = CompassAPI(debug_logger=logging.getLogger("compass_api_sdk"))

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

Release files for compass_api_sdk 2.2.115rc2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for compass_api_sdk 2.2.115rc2
File	Size	Uploaded
compass_api_sdk-2.2.115rc2.tar.gz	281.1 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for compass_api_sdk 2.2.115rc2
File	Interpreter	ABI	Platform	Reset
compass_api_sdk-2.2.115rc2-py3-none-any.whl 637.6 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 918.6 kB

Release files / compass_api_sdk-2.2.115rc2.tar.gz

Download URL	compass_api_sdk-2.2.115rc2.tar.gz
Size	281.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`3ae0d15fc355e6d5b834e87fa5e08bef9f1e7583e97ddceb4a542f41f7f0034c`
BLAKE2b-256 checksum How to use checksums	`b7d0eddd9dcb93e3e8acdbb24623b2b16a9b085715286965704b7b1686892b16`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.5.1 CPython/3.12.14 Linux/6.17.0-1022-azure`

Release files / compass_api_sdk-2.2.115rc2-py3-none-any.whl

Download URL	compass_api_sdk-2.2.115rc2-py3-none-any.whl
Size	637.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`50e44fe753d6f9aab32fd341f5eda3dfe965bdcb58f20d54c6ccd79757addd16`
BLAKE2b-256 checksum How to use checksums	`5cb14c3a50146f03ff6fff6d55aec6e22fc21f81ce124e93e8a56aa388240b36`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.5.1 CPython/3.12.14 Linux/6.17.0-1022-azure`