Decoded ShredStream — Python client

Python client for the Decoded ShredStream of ShredStream.com: pre-execution Solana transactions, decoded from shreds — the serialized VersionedTransaction, its signatures and its slot, delivered over gRPC or UDP push the moment they propagate.

Before execution — transactions carry no status, logs, balance changes or inner instructions, and some will fail on-chain. Use a post-execution source to confirm.

The client is synchronous and blocking: iterating it returns one transaction at a time on the calling thread.

pip install decoded-shredstream

from decoded_shredstream import Client, Filter, GrpcConfig

with Client.grpc(GrpcConfig(endpoint=endpoint, token=token,
                            filters={"all": Filter()})) as client:
    for update in client:
        print(update.slot, update.signature)

Requirements — Python 3.10 or later, and a Decoded ShredStream subscription on ShredStream.com. Extras: solana for parse(), fast for a Rust base58.

With the extras:

pip install "decoded-shredstream[solana,fast]"

🔑 Access

Decoded ShredStream is a subscription product, available from ShredStream.com. One subscription covers both transports, and you can move from one to the other whenever you need to.

• gRPC — you receive an endpoint and an access token. Use the endpoint exactly as issued.
• UDP — you register your server's IP and port; datagrams are pushed to it.

Choosing a transport

Both carry the same data; they differ on what the protocol guarantees.

⚡ Quickstart — gRPC

from decoded_shredstream import Client, Filter, GrpcConfig

with Client.grpc(
    GrpcConfig(
        endpoint="your-endpoint.shredstream.com:PORT",
        token="YOUR_TOKEN",
        filters={"all": Filter()},
    )
) as client:
    for update in client:
        print(update.slot, len(update.data), list(update.filters))

Client.grpc connects and subscribes before returning.

📡 Quickstart — UDP

from decoded_shredstream import Client, UdpConfig

with Client.udp(UdpConfig(port=8002)) as client:
    print("listening on", client.local_addr)
    for update in client:
        print(update.slot, len(update.data), update.signature.hex())

8002 is only an example: bind whichever port you registered in your account.

🔍 Transaction parsing

Every transaction exposes update.data, in the standard Solana wire format, and its signatures without any decoding:

import base58

update.signature                              # first signature, raw 64 bytes
update.signatures                             # every signature
base58.b58encode(update.signature).decode()   # to display one

Everything else is available through parse(), which returns a solders.transaction.VersionedTransaction and requires the solana extra:

for update in client:
    message = update.parse().message
    keys = message.account_keys
    programs = {str(keys[ix.program_id_index]) for ix in message.instructions}
    print(update.slot, keys[0], len(message.instructions), sorted(programs))

Without the solana extra, parse() raises ImportError.

🎯 Filters

Filters exist on the gRPC transport only. They are evaluated by the server; the client never filters locally. UDP delivers the full stream.

A subscription carries a map of named filters. Each response is tagged with the names that matched it, exposed as update.filters.

from decoded_shredstream import Client, Filter, GrpcConfig

client = Client.grpc(
    GrpcConfig(
        endpoint=endpoint,
        token=token,
        filters={
            "watched": Filter(include=[account]),
            "everything": Filter(),
        },
    )
)

Semantics

A Filter holds three lists of base58 account keys, matched against the accounts a transaction touches. The three conditions are ANDed, and an empty list adds no constraint — Filter() matches every transaction.

Matching uses the account keys carried in the transaction, signers included. Addresses resolved through an Address Lookup Table cannot be filtered on. A transaction matching several filters is delivered once.

Replacing filters mid-stream

update_filters replaces the whole map atomically. The server applies it without a reconnect and without a gap in the data, and the new map is the one any later reconnection re-sends.

client.update_filters({"watched": Filter(include=[account])})

🔄 Errors & reconnection

Recoverable interruptions never reach you: the client reconnects on its own and re-sends the current filter map. Only a refused token, a session closed by the server and a rejected filter map end the stream, raised once by the iteration:

from decoded_shredstream import StreamError

try:
    for update in client:
        ...
except StreamError as e:
    print("stream ended:", e)

Every exception, the backoff policy and the telemetry notices are in docs/errors.md.

📖 Documentation

This README is what you need to receive transactions. The rest lives beside it:

💡 Examples

The examples/ directory contains runnable programs; each reads its configuration from the environment.

DECODED_SHREDSTREAM_UDP_PORT=8002 python examples/udp_quickstart.py
DECODED_SHREDSTREAM_ENDPOINT=your-endpoint.shredstream.com:PORT DECODED_SHREDSTREAM_TOKEN=... python examples/grpc_quickstart.py
DECODED_SHREDSTREAM_ENDPOINT=your-endpoint.shredstream.com:PORT DECODED_SHREDSTREAM_TOKEN=... ACCOUNT=<base58> python examples/grpc_filters.py

⚖️ License

Apache-2.0. See LICENSE.