Skip to main content
decdn is a Python client for Python 3.11 to 3.13. It speaks HTTP to a decdn gateway. The gateway pays for every pull and verifies it. The SDK hashes the bytes again with BLAKE3 wherever it holds a whole blob named by its hash. It needs no wallet library. Client is synchronous and AsyncClient is its asyncio twin: both take the same arguments and return the same shapes.
The package is on PyPI. Python 3.14 is not yet supported, because coincurve ships no 3.14 wheels.

Which gateway

The gateway’s HTTP contract is in appendix-gateway. The decdn package 0.1 works with any loopback gateway. A public gateway needs decdn v0.3.0 or later, the oldest release whose HTTP contract the SDK supports.

Fetch from a public gateway

A decdn:<hash>/<path> URI names one file of a bundle. The SDK reads the bundle manifest once and caches it, checks the manifest’s own hash, and hashes the file against the entry the manifest gives. A byte window of a file that declares its size comes back as 206:
ByteRange takes an offset and, optionally, a length. The same calls work awaited, and a body can stream instead of being read whole:
A response is a context manager too. Leaving its block closes the connection if the body was not read.

Use the local gateway

A loopback gateway pays with a capability that a pool owner issues to one of the gateway’s delegate keys (ADR 003). Mint the delegate, have the pool owner assign it, then register the capability for the host your requests name:
Without a capability that covers the host, a request fails with PAYMENT_REQUIRED. client.loopback.capabilities() lists the capabilities the gateway holds, and parse_capability decodes a dcap1: token offline. The SDK does not start the gateway. Run decdn gateway yourself, or the decdn/decdn Docker image. A localhost, 127.0.0.1 or ::1 URL, or any client given a token, is a loopback client, so a public gateway you run locally needs another host name, such as decdn.localhost. read_loopback_token(data_dir=None) reads the token from the gateway’s data directory, ~/.decdn/gateway by default.

What the SDK verifies

get takes verify="auto", True or False. The default is "auto", or whatever the client was constructed with. response.verified says what happened: verified being True names the check, not its result. A body is consumed once, by read(), text() or json(), or by iter_bytes(). Chunks reach you before the last one is hashed, so act on the bytes only once the iteration finishes, or once read() returns. A failed check raises the same error again on every later call. On a public gateway, a site rewrites HTML and CSS as it serves them, so a verified request fetches those files by their own hash. Pass verify=True to refuse anything that cannot be verified: such a request fails with CONFIG.

When the gateway does not pay

A public gateway answers 402 when its allowance is spent and 503 when its pool cannot pay. They reach your code as a DecdnError with code PAYMENT_REQUIRED or POOL_UNFUNDED, and with retry_after_secs and fallback_uri, the canonical decdn: URI. Fetch that URI with a paying client of your own (decdn get), or wait and retry. The SDK retries nothing on its own. get(uri, retry=True) waits out one Retry-After on a 402, 429 or 503 that sends one, and tries once more, and retry=30.0 does so only when the wait is at most 30 seconds.

Point a namespace

The owner of a namespace on the PublisherRegistry points it at a bundle. The public gateway then serves that bundle at https://<ns>.decdn.link/:
A wallet can sign instead: any object with sign_typed_data(typed_data) -> str is a TypedDataSigner. An eth-account LocalAccount returns a SignedMessage, so it needs a small adapter:
Then pass signer=AccountSigner(account). The pointer is an EIP-712 signature over the namespace, the bundle’s manifest hash and a sequence number, which defaults to the current Unix second. pointer_typed_data gives the typed data to a wallet that signs it. The chain id and registry are the deployment the gateway verifies against. The gateway stores a pointer only when its signer owns the namespace and its sequence number is above the last one from that signer. The package README has the full API and every error code: decdn/sdk-python.