Official Python client for the EconDash API. pip install econdash, then search indicators, load time series into pandas and cite sources.

The official Python package wraps the REST API: typed models, clear errors, sync and async clients, and optional pay-per-call for AI agents (x402 on Base, MPP on Tempo and Solana).

PyPI: pypi.org/project/econdash
Source and examples: github.com/econdash/econdash-python

Install

pip install econdash

Python 3.10+. Dependencies: httpx and pydantic.

First calls

from econdash import EconDash

ed = EconDash()                                   # free trial, no key needed

ed.search_indicators("inflation")[:3]             # list[Indicator]
ed.get_indicator("gdp-nominal")                   # source, licence, freshness
s = ed.get_series("gdp-nominal", "USA", start=2000)
ed.list_countries()
ed.top_countries("gdp-nominal", year=2024, limit=10)
ed.cite("gdp-nominal", "USA").citation.text

Indicators accept the slug from chart URLs (gdp-nominal in /chart/gdp-nominal/USA) or the API code (world_bank__gdp_nominal).

Into pandas

import pandas as pd

df = pd.DataFrame([p.model_dump() for p in s.data]).set_index("date")

Without a key the client uses the free trial: 300 requests/day, 30/minute, 10 countries (USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR) and 50 core indicators. Anything else (another country or indicator, or more requests) answers 402. The client then raises EconDashPaymentRequired, unless you gave it an API key or a wallet.

For full access create a key in the dashboard:

ed = EconDash(api_key="ed_...")   # or set ECONDASH_API_KEY

A key from an active subscription opens every indicator and country with full history and no per-IP trial limits, on every method including cite(): 10,000 requests per month, per-endpoint limits of 60–120 requests per minute. With a key the client never pays per call.

Errors

Exception	HTTP	Meaning
`EconDashAuthError`	401 / 403	Bad key or inactive subscription
`EconDashNotFound`	404	Unknown indicator or country
`EconDashRateLimitError`	429	Quota exhausted, see `retry_after`
`EconDashPaymentRequired`	402	Outside the trial: pay per call or use a key. `challenge` holds the x402 requirements, `www_authenticate` the MPP ones

Pay per call (x402 and MPP)

AI agents without an account can pay each call in USDC, see Agent payments. Payments are off by default. The client pays only with a wallet and max_usd_per_call, refuses anything more expensive before signing. Calls the free trial covers are not paid; once the free quota is used up they are paid like any other call.

Rail	Install	Argument
x402, USDC on Base	`pip install "econdash[x402]"`	`x402_signer=Account.from_key(...)` (eth-account)
MPP, USDC on Tempo	`pip install "econdash[tempo]"` (Python 3.11+)	`tempo_account=TempoAccount.from_key(...)` (pympp)
MPP, USDC on Solana	`pip install "econdash[solana]"`	`solana_keypair=Keypair.from_base58_string(...)` (solders)

from econdash import EconDash
from solders.keypair import Keypair

ed = EconDash(
    solana_keypair=Keypair.from_base58_string(AGENT_SOLANA_KEY),
    max_usd_per_call=0.05,
)
ed.get_series("gdp-nominal", "ZWE")   # outside the trial: one paid call
ed.get_series("gdp-nominal", "USA")   # inside the trial: free

With several wallets the client tries x402, then Tempo, then Solana. On Solana the API waits for on-chain confirmation, so a paid call can take up to ~40 seconds.

Async

from econdash import AsyncEconDash

async with AsyncEconDash() as ed:
    s = await ed.get_series("cpi-inflation-rate-percent", "DEU", start=2010)

Citing

Every indicator carries source_url, license_name and attribution_text; ed.cite(...) returns ready text, short and Markdown citations. To cite the package itself, use the "Cite this repository" button on GitHub.

Python SDK