|
| 1 | +# openchainbench |
| 2 | + |
| 3 | +Official Python client for [OpenChainBench](https://openchainbench.com), the live, reproducible benchmark suite for crypto infrastructure (RPC latency, bridge fees, perp venues, oracle deviation, and more). |
| 4 | + |
| 5 | +[](https://pypi.org/project/openchainbench/) |
| 6 | +[](https://pypi.org/project/openchainbench/) |
| 7 | +[](https://pypi.org/project/openchainbench/) |
| 8 | +[](https://github.com/ChainBench/OpenChainBench/blob/main/LICENSE) |
| 9 | + |
| 10 | +The data served by openchainbench.com is published under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Attribute with a link back to the benchmark page (`pageUrl` on every payload). |
| 11 | + |
| 12 | +## Install |
| 13 | + |
| 14 | +```bash |
| 15 | +pip install openchainbench |
| 16 | +``` |
| 17 | + |
| 18 | +Requires Python 3.10+. |
| 19 | + |
| 20 | +## Quick start |
| 21 | + |
| 22 | +```python |
| 23 | +from openchainbench import OpenChainBench |
| 24 | + |
| 25 | +with OpenChainBench() as ocb: |
| 26 | + for bench in ocb.list_benchmarks(): |
| 27 | + if bench.leader: |
| 28 | + print(f"{bench.title}: {bench.leader.name} -> {bench.value}") |
| 29 | +``` |
| 30 | + |
| 31 | +### Fetch one benchmark |
| 32 | + |
| 33 | +```python |
| 34 | +from openchainbench import OpenChainBench |
| 35 | + |
| 36 | +with OpenChainBench() as ocb: |
| 37 | + bench = ocb.get_benchmark("bridge-fee") |
| 38 | + print(bench.headline) |
| 39 | + for row in bench.rankings[:3]: |
| 40 | + print(row.slug, row.ms.p50, row.success_rate) |
| 41 | +``` |
| 42 | + |
| 43 | +### Fetch a time series |
| 44 | + |
| 45 | +```python |
| 46 | +from openchainbench import OpenChainBench |
| 47 | + |
| 48 | +with OpenChainBench() as ocb: |
| 49 | + series = ocb.get_series("bridge-fee", range="24h") |
| 50 | + for provider in series.providers: |
| 51 | + print(provider.name, provider.values[-1]) |
| 52 | +``` |
| 53 | + |
| 54 | +### Filter by chain or region |
| 55 | + |
| 56 | +```python |
| 57 | +bench = ocb.get_benchmark("network-fees", chain="ethereum") |
| 58 | +series = ocb.get_series("network-fees", range="7d", chain="ethereum", region="eu-west") |
| 59 | +``` |
| 60 | + |
| 61 | +## Error handling |
| 62 | + |
| 63 | +The client maps HTTP responses to a typed exception hierarchy so callers |
| 64 | +can react to intent rather than status codes. |
| 65 | + |
| 66 | +```python |
| 67 | +from openchainbench import ( |
| 68 | + OpenChainBench, |
| 69 | + NotFoundError, |
| 70 | + RateLimitError, |
| 71 | + APIUnavailableError, |
| 72 | +) |
| 73 | + |
| 74 | +with OpenChainBench() as ocb: |
| 75 | + try: |
| 76 | + ocb.get_benchmark("not-a-real-slug") |
| 77 | + except NotFoundError: |
| 78 | + ... |
| 79 | + except RateLimitError as exc: |
| 80 | + print(f"retry after {exc.retry_after_sec}s") |
| 81 | + except APIUnavailableError: |
| 82 | + # cold cache or Prom blackout, retry later |
| 83 | + ... |
| 84 | +``` |
| 85 | + |
| 86 | +## API reference |
| 87 | + |
| 88 | +| Method | Endpoint | Returns | |
| 89 | +|---|---|---| |
| 90 | +| `list_benchmarks()` | `GET /api/citable` | `list[BenchmarkSummary]` | |
| 91 | +| `fetch_citable_index()` | `GET /api/citable` | `CitableIndex` | |
| 92 | +| `get_benchmark(slug, *, chain=None, region=None)` | `GET /api/stat/<slug>` | `Benchmark` | |
| 93 | +| `get_series(slug, *, range="24h", chain=None, region=None, providers=None)` | `GET /api/series/<slug>` | `Series` | |
| 94 | + |
| 95 | +All models are immutable dataclasses (`frozen=True`). |
| 96 | + |
| 97 | +## Rate limits |
| 98 | + |
| 99 | +The public API allows 60 requests per minute per IP. The client surfaces |
| 100 | +HTTP 429 as a `RateLimitError` with a `retry_after_sec` attribute. |
| 101 | + |
| 102 | +## Citation |
| 103 | + |
| 104 | +If you use the data in a paper, post, or product, please link the |
| 105 | +benchmark page. The license is CC-BY-4.0. Every payload includes a |
| 106 | +ready-to-paste `quote` field that already contains the attribution. |
| 107 | + |
| 108 | +## Links |
| 109 | + |
| 110 | +- Site: <https://openchainbench.com> |
| 111 | +- Docs: <https://openchainbench.com/docs> |
| 112 | +- Repository: <https://github.com/ChainBench/OpenChainBench> |
| 113 | +- Issues: <https://github.com/ChainBench/OpenChainBench/issues> |
| 114 | + |
| 115 | +## License |
| 116 | + |
| 117 | +MIT. The data fetched from the API stays under CC-BY-4.0; this client |
| 118 | +license only covers the code. |
0 commit comments