API reference
mobula
mobula-py: a typed Python client for the Mobula API.
Example
from mobula import MobulaClient client = MobulaClient(api_key="your-api-key") data = client.get_market_data(asset="Bitcoin") print(data.price)
AsyncMobulaClient
An asyncio client for the Mobula REST API.
This is the async/await counterpart of :class:~mobula.MobulaClient
and exposes the same methods and behaviour (auth header, data unwrapping,
retry on 429/5xx) backed by an :class:httpx.AsyncClient.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_key
|
Optional[str]
|
Mobula API key. When omitted, requests are unauthenticated and subject to the demo/free-tier rate limits. |
None
|
base_url
|
str
|
Override the API base URL (defaults to the production API). |
DEFAULT_BASE_URL
|
timeout
|
float
|
Per-request timeout in seconds. |
DEFAULT_TIMEOUT
|
max_retries
|
int
|
Maximum number of retries for rate-limited / server errors. |
DEFAULT_MAX_RETRIES
|
backoff_factor
|
float
|
Base multiplier for exponential backoff, in seconds. |
DEFAULT_BACKOFF_FACTOR
|
client
|
Optional[AsyncClient]
|
An existing :class: |
None
|
Example
import asyncio from mobula import AsyncMobulaClient async def main(): ... async with AsyncMobulaClient(api_key="your-api-key") as client: ... btc = await client.get_market_data(asset="Bitcoin") ... print(btc.price) asyncio.run(main())
aclose()
async
Close the underlying HTTP client (only if this instance created it).
get_market_data(*, asset=None, symbol=None, blockchain=None)
async
Fetch real-time market data for a single asset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset
|
Optional[str]
|
Asset name or on-chain contract address (e.g. |
None
|
symbol
|
Optional[str]
|
Ticker symbol (e.g. |
None
|
blockchain
|
Optional[str]
|
Chain identifier to disambiguate on-chain assets. |
None
|
Returns:
| Type | Description |
|---|---|
MarketData
|
The parsed :class: |
get_multi_market_data(*, assets, blockchains=None)
async
Fetch market data for many assets in a single request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
assets
|
list[str]
|
Asset names, symbols, or contract addresses. |
required |
blockchains
|
Optional[list[str]]
|
Optional per-asset chains, matched by order. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, MarketData]
|
A mapping of asset key to its :class: |
get_metadata(*, asset=None, symbol=None, blockchain=None)
async
Fetch descriptive metadata (logo, description, socials) for an asset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset
|
Optional[str]
|
Asset name or on-chain contract address. |
None
|
symbol
|
Optional[str]
|
Ticker symbol. |
None
|
blockchain
|
Optional[str]
|
Chain identifier to disambiguate on-chain assets. |
None
|
Returns:
| Type | Description |
|---|---|
Metadata
|
The parsed :class: |
get_market_history(*, asset=None, symbol=None, blockchain=None, from_timestamp=None, to_timestamp=None)
async
Fetch historical price/OHLCV candles for an asset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset
|
Optional[str]
|
Asset name or on-chain contract address. |
None
|
symbol
|
Optional[str]
|
Ticker symbol. |
None
|
blockchain
|
Optional[str]
|
Chain identifier to disambiguate on-chain assets. |
None
|
from_timestamp
|
Optional[int]
|
Start of the window, in milliseconds since epoch. |
None
|
to_timestamp
|
Optional[int]
|
End of the window, in milliseconds since epoch. |
None
|
Returns:
| Type | Description |
|---|---|
list[OHLCV]
|
A list of :class: |
get_blockchains()
async
List the blockchains supported by Mobula.
Returns:
| Type | Description |
|---|---|
list[Blockchain]
|
A list of :class: |
get_wallet_portfolio(*, wallet, blockchains=None)
async
Fetch the aggregated portfolio for a wallet address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wallet
|
str
|
The wallet address to inspect. |
required |
blockchains
|
Optional[list[str]]
|
Optional list of chains to restrict the query to. |
None
|
Returns:
| Type | Description |
|---|---|
WalletPortfolio
|
The parsed :class: |
get_wallet_transactions(*, wallet, blockchains=None)
async
Fetch on-chain transactions for a wallet address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wallet
|
str
|
The wallet address to inspect. |
required |
blockchains
|
Optional[list[str]]
|
Optional list of chains to restrict the query to. |
None
|
Returns:
| Type | Description |
|---|---|
list[WalletTransaction]
|
A list of :class: |
MobulaClient
A synchronous client for the Mobula REST API.
The client wraps an :class:httpx.Client, transparently adds the
Authorization header when an api_key is supplied, unwraps the
data envelope returned by every endpoint, and retries on HTTP 429 and
5xx responses with exponential backoff.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_key
|
Optional[str]
|
Mobula API key. When omitted, requests are unauthenticated and are subject to the demo/free-tier rate limits (free keys are available at https://mobula.io). |
None
|
base_url
|
str
|
Override the API base URL (defaults to the production API). |
DEFAULT_BASE_URL
|
timeout
|
float
|
Per-request timeout in seconds. |
DEFAULT_TIMEOUT
|
max_retries
|
int
|
Maximum number of retries for rate-limited / server errors. |
DEFAULT_MAX_RETRIES
|
backoff_factor
|
float
|
Base multiplier for exponential backoff, in seconds. |
DEFAULT_BACKOFF_FACTOR
|
client
|
Optional[Client]
|
An existing :class: |
None
|
Example
from mobula import MobulaClient with MobulaClient(api_key="your-api-key") as client: ... btc = client.get_market_data(asset="Bitcoin") ... print(btc.price)
close()
Close the underlying HTTP client (only if this instance created it).
get_market_data(*, asset=None, symbol=None, blockchain=None)
Fetch real-time market data for a single asset.
Provide at least one of asset (name or contract address), symbol
(ticker), optionally narrowed by blockchain.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset
|
Optional[str]
|
Asset name or on-chain contract address (e.g. |
None
|
symbol
|
Optional[str]
|
Ticker symbol (e.g. |
None
|
blockchain
|
Optional[str]
|
Chain identifier to disambiguate on-chain assets. |
None
|
Returns:
| Type | Description |
|---|---|
MarketData
|
The parsed :class: |
get_multi_market_data(*, assets, blockchains=None)
Fetch market data for many assets in a single request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
assets
|
list[str]
|
Asset names, symbols, or contract addresses. |
required |
blockchains
|
Optional[list[str]]
|
Optional per-asset chains, matched by order. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, MarketData]
|
A mapping of asset key to its :class: |
get_metadata(*, asset=None, symbol=None, blockchain=None)
Fetch descriptive metadata (logo, description, socials) for an asset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset
|
Optional[str]
|
Asset name or on-chain contract address. |
None
|
symbol
|
Optional[str]
|
Ticker symbol. |
None
|
blockchain
|
Optional[str]
|
Chain identifier to disambiguate on-chain assets. |
None
|
Returns:
| Type | Description |
|---|---|
Metadata
|
The parsed :class: |
get_market_history(*, asset=None, symbol=None, blockchain=None, from_timestamp=None, to_timestamp=None)
Fetch historical price/OHLCV candles for an asset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset
|
Optional[str]
|
Asset name or on-chain contract address. |
None
|
symbol
|
Optional[str]
|
Ticker symbol. |
None
|
blockchain
|
Optional[str]
|
Chain identifier to disambiguate on-chain assets. |
None
|
from_timestamp
|
Optional[int]
|
Start of the window, in milliseconds since epoch. |
None
|
to_timestamp
|
Optional[int]
|
End of the window, in milliseconds since epoch. |
None
|
Returns:
| Type | Description |
|---|---|
list[OHLCV]
|
A list of :class: |
get_blockchains()
List the blockchains supported by Mobula.
Returns:
| Type | Description |
|---|---|
list[Blockchain]
|
A list of :class: |
get_wallet_portfolio(*, wallet, blockchains=None)
Fetch the aggregated portfolio for a wallet address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wallet
|
str
|
The wallet address to inspect. |
required |
blockchains
|
Optional[list[str]]
|
Optional list of chains to restrict the query to. |
None
|
Returns:
| Type | Description |
|---|---|
WalletPortfolio
|
The parsed :class: |
get_wallet_transactions(*, wallet, blockchains=None)
Fetch on-chain transactions for a wallet address.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wallet
|
str
|
The wallet address to inspect. |
required |
blockchains
|
Optional[list[str]]
|
Optional list of chains to restrict the query to. |
None
|
Returns:
| Type | Description |
|---|---|
list[WalletTransaction]
|
A list of :class: |
MobulaAPIError
Bases: MobulaError
Raised when the Mobula API returns a non-success HTTP status.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
The HTTP status code returned by the API, when known. |
|
response_body |
The raw response body, when available, for debugging. |
MobulaAuthError
Bases: MobulaAPIError
Raised on authentication failures (HTTP 401/403).
Usually indicates a missing or invalid api_key.
MobulaError
Bases: Exception
Base class for every error raised by mobula-py.
MobulaRateLimitError
Bases: MobulaAPIError
Raised when the API responds with HTTP 429 (rate limited).
Attributes:
| Name | Type | Description |
|---|---|---|
retry_after |
Seconds to wait before retrying, parsed from the
|
OHLCV
Bases: MobulaModel
A single open/high/low/close/volume candle from price history.
from_row(row)
classmethod
Build an :class:OHLCV from a positional [time, o, h, l, c, v] row.
Mobula's GET /market/history returns candles as positional arrays
rather than objects; this helper maps them onto named fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
row
|
list[Any]
|
A sequence of |
required |
Returns:
| Type | Description |
|---|---|
OHLCV
|
The parsed candle. |
Blockchain
Bases: MobulaModel
A blockchain supported by Mobula, from GET /market/blockchains.
MarketData
Bases: MobulaModel
Real-time market data for a single asset.
Returned by GET /market/data and as the per-asset value of
GET /market/multi-data.
Metadata
Bases: MobulaModel
Descriptive metadata for an asset, returned by GET /metadata.
WalletAsset
Bases: MobulaModel
A single holding within a wallet portfolio.
WalletPortfolio
Bases: MobulaModel
Aggregated portfolio for one or more wallets.
Returned by GET /wallet/portfolio.
WalletTransaction
Bases: MobulaModel
A single on-chain transaction from GET /wallet/transactions.