High-performance Python library for parsing Solana DEX events in real-time via Yellowstone gRPC
中文 | English | Website | Telegram | Discord
Current version: 0.9.1. Read the migration notes before upgrading; see the changelog for historical changes.
- SDK Versions and Related SDKs
- How to use
- What This SDK Is For
- Trade provenance and parsing boundaries
- Examples
- Protocols
- Documentation
Repositories are versioned independently; follow each SDK’s installation guide for compatible dependencies.
| Language | Repository | Purpose | Version |
|---|---|---|---|
| Rust | sol-parser-sdk | DEX transaction and account event parsing | v0.9.1 |
| Node.js | sol-parser-sdk-nodejs | DEX transaction and account event parsing | v0.9.1 |
| Python | sol-parser-sdk-python | DEX transaction and account event parsing | v0.9.1 |
| Go | sol-parser-sdk-golang | DEX transaction and account event parsing | v0.9.1 |
| Rust | sol-trade-sdk | Transaction building, signing and multi-channel submission | v9.0.1 |
| Node.js | sol-trade-sdk-nodejs | Transaction building, signing and multi-channel submission | v9.0.1 |
| Python | sol-trade-sdk-python | Transaction building, signing and multi-channel submission | v9.0.1 |
| Go | sol-trade-sdk-golang | Transaction building, signing and multi-channel submission | v9.0.1 |
| Rust | sol-shred-sdk | Raw shred decoding and ShredStream instruction events | v6.0.1 |
| Rust | solana-streamer | gRPC / ShredStream subscriptions and event streaming | v5.0.0 |
| Rust | sol-trade-router-sdk | On-chain multi-hop router and client SDK | v0.3.0 |
From PyPI
pip install sol-parser-sdk-python==0.9.1From source
git clone https://github.com/0xfnzero/sol-parser-sdk-python
cd sol-parser-sdk-python
pip install -e .
pip install grpcio grpcio-tools protobuf base58 python-dotenvAt the package root (next to pyproject.toml):
cp .env.example .env
# Set GRPC_URL (or GRPC_ENDPOINT) and GRPC_AUTH_TOKEN or GRPC_TOKENRun examples from that directory so .env is picked up (same idea as the Node.js package).
CLI overrides: --grpc-url / -g, --grpc-token / --token (also --grpc-url=https://host:443). Rust-compatible names: GRPC_AUTH_TOKEN (same as sol-parser-sdk examples), GRPC_ENDPOINT (alias for URL). Legacy env: GEYSER_ENDPOINT / GEYSER_API_TOKEN. Precedence: CLI > GRPC_URL / GRPC_ENDPOINT > GEYSER_* > defaults; token: CLI > GRPC_AUTH_TOKEN > GRPC_TOKEN > GEYSER_API_TOKEN. Explicit shell export wins over .env; python-dotenv does not overwrite existing variables.
Helpers: sol_parser.env_config (parse_grpc_credentials, require_grpc_env, parse_shredstream_url, …), re-exported from sol_parser.
python examples/pumpfun_quick_test.pyRequires GRPC_URL (or GRPC_ENDPOINT) and (for most providers) GRPC_AUTH_TOKEN or GRPC_TOKEN in .env or the environment. You can pass credentials on the command line instead; see step 2.
import asyncio
import os
import base58
from sol_parser import parse_logs_only
from sol_parser.grpc_client import YellowstoneGrpc
from sol_parser.grpc_types import Protocol, SubscribeCallbacks, transaction_filter_for_protocols
async def main():
endpoint = (
os.environ.get("GRPC_URL", "").strip()
or os.environ.get("GRPC_ENDPOINT", "").strip()
or os.environ.get("GEYSER_ENDPOINT", "solana-yellowstone-grpc.publicnode.com:443")
)
token = (
os.environ.get("GRPC_AUTH_TOKEN", "").strip()
or os.environ.get("GRPC_TOKEN", "").strip()
or os.environ.get("GEYSER_API_TOKEN", "")
)
client = YellowstoneGrpc(endpoint)
if token:
client.set_x_token(token)
await client.connect()
filter_ = transaction_filter_for_protocols([Protocol.PUMP_FUN, Protocol.PUMP_SWAP])
filter_.vote = False
filter_.failed = False
def on_update(update):
if update.transaction is None or update.transaction.transaction is None:
return
tx_info = update.transaction.transaction
slot = update.transaction.slot
logs = tx_info.log_messages
if not logs:
return
sb = bytes(tx_info.signature) if tx_info.signature else b""
sig = base58.b58encode(sb).decode("ascii") if len(sb) == 64 else ""
events = parse_logs_only(
logs, sig, slot, None, subscribe_tx_info=tx_info
) # tx_info from gRPC update — fills accounts from instruction keys
for ev in events:
print(ev)
sub = await client.subscribe_transactions(
filter_,
SubscribeCallbacks(on_update=on_update, on_error=print, on_end=lambda: None),
)
print("subscribed", sub.id)
try:
await asyncio.Event().wait()
except KeyboardInterrupt:
pass
await client.disconnect()
asyncio.run(main())Lighter path: parse_logs_only(logs, …) only needs log messages from the update (no full wire transaction).
Python includes a native ShredStream client (ShredStreamClient, ShredStreamConfig) plus the same env/CLI helpers as Node (parse_shredstream_url: SHREDSTREAM_URL / SHRED_URL, --url / -u / --endpoint=). Install the optional extra with pip install 'sol-parser-sdk-python[shredstream]'. ShredStream uses its own endpoint, not GRPC_URL.
The Python ShredStream hot path uses strict static-account parsing by default. Supply loaded addresses or a slot-aware prewarmed-cache resolver for V0 ALT instructions; unresolved instructions are skipped. Legacy placeholders require the explicit parse_shred_transaction_best_effort API. Unknown Pump.fun wrappers produce unresolved PumpFunTrade candidates with third_program; raw shreds cannot reconstruct arbitrary CPI. Inner CPI/log-only events still require the Yellowstone/RPC paths.
This is the Python implementation of the FnZero Solana DEX parser SDK for asyncio services, research scripts, indexers, copy-trading systems, sniper pipelines, and backend jobs that need normalized real-time DEX events.
| Area | Coverage |
|---|---|
| Parser inputs | Yellowstone gRPC, ShredStream, RPC transactions, encoded transactions, protocol account data |
| DEX protocols | PumpFun, PumpSwap, Pump Fees, Raydium LaunchLab, Raydium CPMM, Raydium CLMM, Raydium AMM V4, Meteora DAMM v2, Meteora DLMM, Meteora DBC, Orca Whirlpool |
| Use cases | Real-time DEX event parsing, token launch monitoring, copy trading, sniper bots, analytics notebooks, JSON event pipelines |
| Runtime | Python 3.10+, asyncio workers, backend services, data pipelines, low-latency bot infrastructure |
gRPC/RPC use supplied execution metadata and actual CPI instructions; Shred sees outer instructions and locally resolved accounts. An unknown third-party instruction referencing Pump.fun in its own accounts can produce a PumpFunTrade candidate with the original input in third_program and Unresolved status. This does not establish execution, direction or amounts. Buy/sell-only filters do not treat an unknown direction as a fill.
The parsing hot path performs no RPC. Check parse_status before interpreting defaults as amounts. Original account order and instruction bytes remain in third_program; transaction position and receive time remain in event metadata. A local Shred index is not confirmed slot-wide execution order. See wrapped transactions and cross-language contracts.
From the package root after pip install -e .. Run with python examples/<file>.py. Scripts are written to mirror the output layout and env names of sol-parser-sdk/examples (Rust); streaming uses subscribe_transactions + parse_logs_only with the same program IDs as TransactionFilter::for_protocols in Rust.
| Description | Run command | Source |
|---|---|---|
| PumpFun | ||
| PumpFun trade filtering | python examples/pumpfun_trade_filter.py |
pumpfun_trade_filter.py |
| PumpFun events + metrics | python examples/pumpfun_with_metrics.py |
pumpfun_with_metrics.py |
| Quick PumpFun connection test | python examples/pumpfun_quick_test.py |
pumpfun_quick_test.py |
| PumpSwap | ||
| PumpSwap ultra-low latency | python examples/pumpswap_low_latency.py |
pumpswap_low_latency.py |
| PumpSwap events + metrics | python examples/pumpswap_with_metrics.py |
pumpswap_with_metrics.py |
| Meteora DAMM | ||
| Meteora DAMM V2 events | python examples/meteora_damm_grpc.py |
meteora_damm_grpc.py |
| Multi-protocol | ||
Subscribe to every program in Rust Protocol / program_ids |
python examples/multi_protocol_grpc.py |
multi_protocol_grpc.py |
| Utility | ||
Parse tx by signature (HTTP RPC; not gRPC). TX_SIGNATURE / RPC_URL or SOLANA_RPC_URL in .env or --sig / --rpc. |
python examples/parse_tx_by_signature.py |
parse_tx_by_signature.py |
Env: gRPC examples need GRPC_URL or GRPC_ENDPOINT, plus GRPC_AUTH_TOKEN or GRPC_TOKEN (or legacy GEYSER_*). See .env.example.
PumpFun, PumpSwap, Raydium AMM V4 / CLMM / CPMM, Orca Whirlpool, Meteora DAMM V2 / DLMM, Raydium LaunchLab (see sol_parser/).
parse_logs_only— log-based DEX events from gRPC log messages.format_dex_event_json/dex_event_to_jsonable— pretty-printDexEventas indented JSON (one field per line);repr(ev)is the default dataclass single-line form, not JSON.YellowstoneGrpc— async Yellowstone gRPC client (connect,subscribe_transactions,disconnect).now_micros— microsecond clock (same role as Rustsol_parser_sdk::core::now_micros).transaction_filter_for_protocols/program_ids_for_protocols/account_filter_for_protocols— same program IDs as RustProtocol+for_protocolsingrpc/filter.rs.parse_grpc_credentials/require_grpc_env— load.env+ env + CLI (aligned with sol-parser-sdk-nodejsgrpc_env).
import os
from sol_parser.grpc_client import YellowstoneGrpc
endpoint = os.environ.get("GRPC_URL") or os.environ.get("GRPC_ENDPOINT") or os.environ.get(
"GEYSER_ENDPOINT", "solana-yellowstone-grpc.publicnode.com:443"
)
token = (
os.environ.get("GRPC_AUTH_TOKEN")
or os.environ.get("GRPC_TOKEN")
or os.environ.get("GEYSER_API_TOKEN", "")
)
client = YellowstoneGrpc(endpoint)
if token:
client.set_x_token(token)parse_logs_only can detect create-and-buy patterns from program logs; see the PumpFun examples.
sol-parser-sdk-python/
├── sol_parser/
│ ├── grpc_client.py # YellowstoneGrpc (async connect / subscribe)
│ ├── env_config.py # GRPC_URL, .env, CLI helpers (Node parity)
│ ├── clock.py # now_micros()
│ ├── grpc_types.py # TransactionFilter, SubscribeCallbacks, for_protocols helpers, …
│ ├── parser.py # parse_logs_only, …
│ ├── geyser_pb2.py # Generated proto (Yellowstone)
│ └── …
├── examples/
│ ├── pumpfun_trade_filter.py
│ ├── pumpfun_quick_test.py
│ └── …
├── .env.example
└── pyproject.toml
pip install -e ".[dev]"
pytest tests/Full cross-language API parity is still in progress. See the API migration guide for public behavior and support boundaries, and the examples directory for usage.
Live parser-to-trade integration uses Yellowstone gRPC. See gRPC cache integration and language examples. Quoting and construction read cached state without hot-path RPC.
Shared PumpFun create/create_v2 mainnet fixtures, replay instructions and verification limits are documented in the validation guide.
User examples live in examples; automated regression tests are maintained separately. Obsolete route-intent simulation entry points and their unused snapshots have been removed. See wrapped transaction replay and filters. Shred decodes resolved outer instructions; third-party candidates retain original input in PumpFunTrade.third_program and are not confirmed fills. No RPC runs in the parser hot path.
Native offline CPU benchmark: python -m examples.hot_path_benchmark.
examples/hot_path_benchmark.json fixes warmup and measured iterations for six
signed wrapped-CPI/ALT transactions. Reported percentiles are per six-transaction
batch; fixture decoding and I/O occur before timing. Parsing performs no RPC.
Public wire-decoder dictionaries and resolver callbacks retain base58 strings;
the internal ShredStream path avoids an instruction-data base58 round trip.
MIT — https://github.com/0xfnzero/sol-parser-sdk-python
- Repository: https://github.com/0xfnzero/sol-parser-sdk-python
- Website: https://fnzero.dev/
- Telegram: https://t.me/fnzero_group
- Discord: https://discord.gg/vuazbGkqQE
Shared stock bridges: 33 official stock/ETF mints and 58 pools. See eleven-SDK catalog and routing alignment for configuration, USDC routing and cache-only boundaries.