> For the complete documentation index, see [llms.txt](https://docs.blinklabs.xyz/blink/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blinklabs.xyz/blink/data-api/delta-sharing.md).

# Delta Sharing

Query Blink data directly from your own environment via Delta Sharing

The [Metrics API](/blink/data-api/metrics.md) returns pre-aggregated time series — the same numbers you see on the dashboard. If you need the underlying transaction-level data, or you want to join Blink data against your own datasets, we can provide access through **Delta Sharing** instead.

### What it is

Delta Sharing is an open protocol for sharing live data across organisations. Rather than exporting CSVs on a schedule or paginating through an API, you point a client at a share and query it directly. The data stays in one place and you always read the current version.

Because the protocol is open, you are not required to run Databricks — any Delta Sharing client works, including:

* **Python** — the `delta-sharing` package, loading straight into a pandas DataFrame
* **Apache Spark** — read a share as a Spark DataFrame or SQL table
* **Databricks** — mount the share as a catalog and query it with SQL

### How access works

We create a *recipient* for your organisation and send you an activation link. That link yields a credential file (`config.share`) holding the endpoint and a bearer token — treat it as a secret. From there, listing and reading tables is a few lines:

```python
import delta_sharing

profile = "config.share"

# See what the share contains
delta_sharing.list_all_tables(profile)

# Load a table into pandas
df = delta_sharing.load_as_pandas(f"{profile}#<share>.<schema>.<table>")
```

Access is scoped to your own organisation's data, and can be revoked or rotated at any time.

### Table columns

The share exposes the transaction table directly, one row per transaction Blink handled for you.

| Column             | Type      | Description                                                                  |
| ------------------ | --------- | ---------------------------------------------------------------------------- |
| `inserted_at`      | Timestamp | When Blink received the transaction                                          |
| `tx_hash`          | String    | Transaction hash                                                             |
| `block_number`     | Long      | Block the transaction landed in. `0` or null when it never landed            |
| `chain_id`         | Integer   | Chain the transaction was submitted on. Always filter on this                |
| `originator`       | String    | Originator ID the transaction was submitted under                            |
| `prio_fee_wei`     | Decimal   | Priority fee, in wei                                                         |
| `mev_recovery_wei` | Decimal   | Gross MEV recovered on the transaction, in wei, before your share is applied |
| `gas_recovery_wei` | Decimal   | Gross gas recovered on the transaction, in wei, before your share is applied |
| `exclusive`        | Boolean   | Whether the transaction was exclusive order flow                             |
| `reverted`         | Boolean   | Whether the transaction reverted on-chain                                    |
| `latency_ms`       | Integer   | Time from receipt to inclusion, in milliseconds                              |
| `error`            | String    | Error detail where one was recorded, otherwise null                          |
| `swap_volume_usd`  | Decimal   | USD swap volume, where the transaction was a swap                            |

#### Working with the recovery columns

`mev_recovery_wei` and `gas_recovery_wei` are the **gross** amounts recovered, not your share of them. To arrive at the figures shown on your dashboard, apply your agreed recovery percentage and convert out of wei:

```sql
SELECT
  date_trunc('day', inserted_at) AS day,
  sum(mev_recovery_wei) * (<your_mev_percentage> / 100) / 1e18 AS mev_recovery
FROM <share>.<schema>.transactions
WHERE chain_id = 1
GROUP BY 1
ORDER BY 1
```

If you only want the finished numbers, the [Metrics API](/blink/data-api/metrics.md) already applies your percentage and returns native-token values.

#### Differences from the dashboard CSV

The CSV export computes several columns at query time, so a few things are named or shaped differently here:

| CSV column                             | In the share                                                                                  |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `priority_fee_gwei`                    | `prio_fee_wei` — wei rather than gwei, so divide by 10^9                                      |
| `tx_originator`                        | `originator`                                                                                  |
| `status`                               | Derive it: `reverted = true` → reverted, else `block_number > 0` → success, else never landed |
| `is_exclusive`                         | Use `exclusive` — the CSV's `1`/`0` column is just a second encoding of it                    |
| `mev_recovery_wei`, `gas_recovery_wei` | Gross rather than your share — see above                                                      |

Rows for transactions that never landed are present, with `block_number` of `0` or null. Filter them out with `block_number > 0` when you only want on-chain activity.

### Requesting access

Delta Sharing is set up per customer rather than self-serve. Email <contact@blinklabs.xyz> and let us know:

* Which chains you need data for
* Which environment you will read from (Databricks, Spark, Python, other)
* Roughly what history you need, and how often you intend to query

We will confirm what can be shared and send the activation link.