# shardd — full documentation

Concatenated source of every guide on shardd.xyz, in sidebar order. Generated at build time; this file is the same markdown the site renders. Drop into an LLM context window for one-shot integration help.

---

# Introduction

Source: https://shardd.xyz/guide/introduction

`shardd` is a globally distributed credit ledger for metered billing.
Credit, debit, and hold accounts from any region — no central
database, no leader, no consensus tax. Edge gateways in `use1`,
`euc1`, and `ape1` accept writes locally and replicate asynchronously
across a private libp2p mesh.

## What you'll do

The whole API surface is essentially three operations:

- `POST /events` — credit, debit, or hold a balance. Idempotent on a caller-supplied nonce.
- `GET /balances?bucket=<scope>` — read every account's balance in a bucket.
- `GET /collapsed/<bucket>/<account>` — read one account's balance and active holds.

Authenticate with `Authorization: Bearer $SHARDD_API_KEY`. Get a key
at [app.shardd.xyz/dashboard/keys](https://app.shardd.xyz/dashboard/keys).

## Mental model

- A **bucket** is your scope: `"orders"`, `"team:acme"`, `"workspace:42"`. Pick one per logical product.
- An **account** within a bucket is whatever holds balance: `"user:alice"`, `"invoice:9821"`, `"key:abc123"`.
- Every event is replicated across the cluster within ~50ms; reads are read-your-writes within a bucket.
- Edges fail over automatically — a single regional outage does not affect availability.

## Where to go next

- [**Quickstart**](/guide/quickstart) — copy-pasteable curl, Rust, Python, TypeScript, Kotlin examples for every operation. Pick a tab; the choice sticks across pages.
- [**SDKs**](/guide/sdks) — package coordinates for the four first-party clients (`shardd` on crates.io / PyPI, `@shardd/sdk` on npm, `xyz.shardd:sdk` on Maven Central) and what every SDK does for free (probe, rank, fail over, idempotency).
- [**CLI**](/guide/cli) — `cargo install shardd-cli` for a terminal-based front-end with browser-based device-flow auth. Same operations as the dashboard.
- [**AI Agent Prompt**](/guide/ai-agent-setup) — drop-in prompt for Claude Code / Cursor / Codex that wires shardd into whatever language and tooling your project already uses.
- [**Public Edge Clients**](/guide/public-edge-clients) — when you're not on a supported language and need to talk HTTPS directly.
- [**Architecture**](/guide/architecture) — how the private mesh and public edge planes are split.

## For LLMs and AI agents

These docs follow the [llmstxt.org](https://llmstxt.org) convention so AI agents can pull them in one fetch:

- [`/llms.txt`](/llms.txt) — index, one line per page.
- [`/llms-full.txt`](/llms-full.txt) — every guide concatenated as raw markdown. Drop into an LLM context window.

Every guide is also served as raw markdown — append `.md` to any
`/guide/<slug>` URL (e.g. [`/guide/quickstart.md`](/guide/quickstart.md)),
or use the **copy as markdown** icon in the top-right of any guide.

---

# Quickstart

Source: https://shardd.xyz/guide/quickstart

`shardd`'s public developer path is HTTPS to regional edge gateways.

Start with one or more bootstrap edge URLs:

- `https://use1.api.shardd.xyz`
- `https://ape1.api.shardd.xyz`
- `https://euc1.api.shardd.xyz`

Get an API key at [app.shardd.xyz → Keys](https://app.shardd.xyz/dashboard/keys)
and export it as `SHARDD_API_KEY`. The tabs below show the same
operations in five forms — pick the one that fits your stack; the
choice sticks across pages.

## Install the SDK

::: code-group

```bash [curl]
# no install — curl ships with every system
```

```toml [rust]
# Cargo.toml
[dependencies]
shardd = "0.1"
tokio  = { version = "1", features = ["full"] }
```

```bash [python]
pip install shardd
```

```bash [typescript]
npm install @shardd/sdk
```

```kotlin [kotlin]
// build.gradle.kts
dependencies {
    implementation("xyz.shardd:sdk:0.1.0")
}
```

:::

## Health check

::: code-group

```bash [curl]
curl -sS https://use1.api.shardd.xyz/gateway/health
```

```rust [rust]
use shardd::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(std::env::var("SHARDD_API_KEY")?)?;
    let health = client.health(None).await?;
    println!("{:?}", health);
    Ok(())
}
```

```python [python]
import os
from shardd import Shardd

shardd = Shardd(os.environ["SHARDD_API_KEY"])
print(shardd.health())
```

```typescript [typescript]
import { Client } from "@shardd/sdk";

const shardd = new Client(process.env.SHARDD_API_KEY!);
console.log(await shardd.health());
```

```kotlin [kotlin]
import xyz.shardd.sdk.Client

val shardd = Client(System.getenv("SHARDD_API_KEY"))
println(shardd.health())
```

:::

## Deposit (credit)

::: code-group

```bash [curl]
curl -sS https://use1.api.shardd.xyz/events \
  -H "Authorization: Bearer $SHARDD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket":"orders","account":"alice","amount":100,"note":"top-up"}'
```

```rust [rust]
use shardd::{Client, CreateEventOptions};

let result = client
    .create_event(
        "orders",
        "alice",
        100,
        CreateEventOptions { note: Some("top-up".into()), ..Default::default() },
    )
    .await?;
println!("balance = {}", result.balance);
```

```python [python]
result = shardd.create_event("orders", "alice", 100, note="top-up")
print("balance =", result.balance)
```

```typescript [typescript]
const result = await shardd.createEvent("orders", "alice", 100, { note: "top-up" });
console.log("balance =", result.balance);
```

```kotlin [kotlin]
import xyz.shardd.sdk.CreateEventOptions

val result = shardd.createEvent(
    "orders", "alice", 100,
    CreateEventOptions(note = "top-up"),
)
println("balance = ${result.balance}")
```

:::

## Charge (debit)

Negative `amount`, plus an `idempotency_nonce` so retries don't
double-charge. If you omit the nonce the SDK generates a UUID v4 for
you — pass one explicitly when you want retries to collapse onto a
known logical op.

::: code-group

```bash [curl]
curl -sS https://use1.api.shardd.xyz/events \
  -H "Authorization: Bearer $SHARDD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "orders",
    "account": "alice",
    "amount": -25,
    "note": "order-9821",
    "idempotency_nonce": "order-9821-charge"
  }'
```

```rust [rust]
let result = client
    .create_event(
        "orders",
        "alice",
        -25,
        CreateEventOptions {
            note: Some("order-9821".into()),
            idempotency_nonce: Some("order-9821-charge".into()),
            ..Default::default()
        },
    )
    .await?;
println!("balance = {}", result.balance);
```

```python [python]
result = shardd.create_event(
    "orders", "alice", -25,
    note="order-9821",
    idempotency_nonce="order-9821-charge",
)
print("balance =", result.balance)
```

```typescript [typescript]
const result = await shardd.createEvent("orders", "alice", -25, {
  note: "order-9821",
  idempotencyNonce: "order-9821-charge",
});
console.log("balance =", result.balance);
```

```kotlin [kotlin]
val result = shardd.createEvent(
    "orders", "alice", -25,
    CreateEventOptions(
        note = "order-9821",
        idempotencyNonce = "order-9821-charge",
    ),
)
println("balance = ${result.balance}")
```

:::

## Read balances

::: code-group

```bash [curl]
curl -sS "https://use1.api.shardd.xyz/balances?bucket=orders" \
  -H "Authorization: Bearer $SHARDD_API_KEY"
```

```rust [rust]
let balances = client.get_balances("orders").await?;
for row in balances.accounts {
    println!("{} = {}", row.account, row.balance);
}
```

```python [python]
balances = shardd.get_balances("orders")
for row in balances.accounts:
    print(f"{row.account} = {row.balance}")
```

```typescript [typescript]
const balances = await shardd.getBalances("orders");
for (const row of balances.accounts) {
  console.log(`${row.account} = ${row.balance}`);
}
```

```kotlin [kotlin]
val balances = shardd.getBalances("orders")
for (row in balances.accounts) {
    println("${row.account} = ${row.balance}")
}
```

:::

---

# Official SDKs

Source: https://shardd.xyz/guide/sdks

`shardd` ships first-party clients for four ecosystems. Every SDK
implements the same edge probe + automatic failover dance, so the
typical app calls a couple of high-level methods and skips the
`/gateway/health` and `/gateway/edges` plumbing.

| Language | Package | Registry | Source |
|---|---|---|---|
| Rust | `shardd` | [crates.io](https://crates.io/crates/shardd) · [docs.rs](https://docs.rs/shardd) | [sdks/rust](https://github.com/shardd-xyz/shardd/tree/main/sdks/rust) |
| Python | `shardd` | [pypi.org](https://pypi.org/project/shardd/) | [sdks/python](https://github.com/shardd-xyz/shardd/tree/main/sdks/python) |
| TypeScript | `@shardd/sdk` | [npmjs.com](https://www.npmjs.com/package/@shardd/sdk) | [sdks/typescript](https://github.com/shardd-xyz/shardd/tree/main/sdks/typescript) |
| Kotlin / JVM | `xyz.shardd:sdk` | [Maven Central](https://central.sonatype.com/artifact/xyz.shardd/sdk) | [sdks/kotlin](https://github.com/shardd-xyz/shardd/tree/main/sdks/kotlin) |
| CLI | `shardd-cli` (binary `shardd`) | [crates.io](https://crates.io/crates/shardd-cli) | [apps/developer-cli](https://github.com/shardd-xyz/shardd/tree/main/apps/developer-cli) |

## Install

::: code-group

```toml [rust]
# Cargo.toml
[dependencies]
shardd = "0.1"
tokio  = { version = "1", features = ["full"] }
```

```bash [python]
pip install shardd
```

```bash [typescript]
npm install @shardd/sdk
```

```kotlin [kotlin]
// build.gradle.kts
dependencies {
    implementation("xyz.shardd:sdk:0.1.0")
}
```

```bash [cli]
cargo install shardd-cli
# then:
shardd auth login
```

:::

## What every SDK does

- **Bootstrap** from a list of edge URLs (defaults to the three prod regions: `use1`, `euc1`, `ape1`).
- **Probe** `/gateway/health` on first use, rank by latency, pin the best healthy candidate.
- **Refresh** the regional directory via `/gateway/edges` on demand.
- **Fail over** on `503` / `504` / timeout — cool off the bad edge for 60 seconds, retry once against the next-best candidate, reuse the same idempotency nonce so retries collapse onto the same logical write.
- **Idempotency** — every `createEvent` carries a nonce. Capture it on your side for safe retries; if you don't pass one, the SDK generates a UUID v4.

See the [Quickstart](/guide/quickstart) for the common calls in every
language, or browse the per-SDK README on GitHub for the full surface
(holds, account detail, `listEvents`, custom edges, etc.).

---

# shardd CLI

Source: https://shardd.xyz/guide/cli

`shardd-cli` is the official command-line client. It speaks the same
HTTPS endpoints the dashboard does, so any operation you can perform
in the browser you can script from a terminal — credit/debit, balance
checks, bucket lifecycle, key management, billing, profile.

## Install

```bash
cargo install shardd-cli
```

The binary lands at `~/.cargo/bin/shardd`.

## Log in

```bash
shardd auth login
```

This opens `https://app.shardd.xyz/cli-authorize?session=…` in your
browser. Hit **Authorize**, copy the 10-character verification code,
paste it back into the waiting CLI. The CLI mints a developer API key
for the host and stashes it at `~/.config/shardd/credentials.toml`
(0600).

The key shows in [the dashboard's Keys page](https://app.shardd.xyz/dashboard/keys)
named `cli/<your-hostname>` — revoke or rotate it the same way you
would any other key.

## Common commands

```bash
shardd auth whoami                       # who am I logged in as?
shardd events create --bucket orders --account alice --amount 100
shardd events list   --bucket orders --account alice --limit 50
shardd balances list --bucket orders     # every account in the bucket
shardd accounts get  --bucket orders --account alice
shardd buckets list                      # paginated, supports --status
shardd buckets create --name new-bucket
shardd buckets archive --name old-bucket
shardd keys list
shardd keys create --name "ci-prod" --scope all:rw
shardd profile get
shardd billing status
shardd edges                             # current regional edge directory
shardd health --edge https://use1.api.shardd.xyz
```

Every command returns pretty-printed JSON on stdout. Pipe to `jq` for
filtering and scripting.

## Environment overrides

- `SHARDD_DASHBOARD_URL` — point the CLI at a different dashboard
  (e.g. `http://localhost:8080` for local dev). Set it once at login
  time; the URL is then persisted in `credentials.toml` so subsequent
  invocations don't need it.
- `--dashboard-url <url>` — per-command override of the above.

## Logging out

```bash
shardd auth logout            # also revokes the issued key on the server
shardd auth logout --local    # delete local creds only; key stays alive
```

## Source

[github.com/shardd-xyz/shardd/tree/main/apps/developer-cli](https://github.com/shardd-xyz/shardd/tree/main/apps/developer-cli) ·
MIT license · published as `shardd-cli` on
[crates.io](https://crates.io/crates/shardd-cli).

---

# Drop-in AI agent prompt

Source: https://shardd.xyz/guide/ai-agent-setup

Paste this into your AI coding agent (Claude Code, Cursor, Codex, Copilot,
Aider, …) and it'll wire `shardd` into whatever language and tooling
this project already uses. No prior shardd knowledge required from the
agent — the prompt is self-contained.

## The prompt

````text
You are integrating `shardd` (a globally distributed credit ledger with
first-party SDKs for Rust, Python, TypeScript, and Kotlin/JVM) into this
project. Your job: pick the right SDK, install it, wire one shared
client, and add the minimum credit / debit / read call sites — without
changing this project's package manager, framework, or env conventions.

1) Detect the language that owns the code path that needs to write/read
   balances. Inspect the repo root and the directory of the file you'll
   be editing:
   - `Cargo.toml`                                       → Rust;       crate `shardd` on crates.io
   - `pyproject.toml` / `requirements.txt` / `setup.py` → Python;     package `shardd` on PyPI
   - `package.json`                                     → TypeScript; package `@shardd/sdk` on npm
   - `build.gradle.kts` / `build.gradle` / `pom.xml`    → Kotlin/JVM; coordinate `xyz.shardd:sdk:0.1.0` on Maven Central
   If multiple are present, pick the one that owns the new feature.
   Ask if ambiguous. If none of the above (Go, Ruby, PHP, …), fall
   back to plain HTTPS per https://shardd.xyz/guide/public-edge-clients
   and stop reading this prompt.

2) Install with the project's existing tooling — read the lockfile to
   figure out which one. Do not switch package managers.
   - npm / yarn / pnpm / bun: add `@shardd/sdk`
   - pip / poetry / uv / pipenv: add `shardd`
   - `cargo add shardd`. If `tokio` isn't already in `Cargo.toml`, add
     `tokio = { version = "1", features = ["full"] }` — the SDK is async.
   - Gradle: add `implementation("xyz.shardd:sdk:0.1.0")` to dependencies.
     Maven: the equivalent `<dependency>` block.

3) Env. Add `SHARDD_API_KEY` to wherever this project already keeps
   env vars: `.env`, `.env.example`, deployment secrets template, Helm
   values, Vercel/Netlify/Doppler config, whatever applies. Never
   hard-code it in source. The human should grab a key from
   https://app.shardd.xyz/dashboard/keys.

4) Construct the client once and share it. The SDK probes the regional
   edge directory lazily on first use, so reuse one instance per
   process. Stash it in whatever singleton/DI pattern this project
   already uses. The constructor just takes the key:
   - TS:     `new Client(process.env.SHARDD_API_KEY!)`
   - Python: `Shardd(os.environ["SHARDD_API_KEY"])`
   - Rust:   `Client::new(std::env::var("SHARDD_API_KEY")?)?` (sync constructor; methods are async)
   - Kotlin: `Client(System.getenv("SHARDD_API_KEY"))` (blocking)

5) Call sites. These four cover ~everything:
   - Credit / debit / hold: `client.create_event(bucket, account, amount, opts)`
     — positive `amount` = credit, negative = debit. Pass an
     `idempotency_nonce` (TS: `idempotencyNonce`) whenever the call
     lives inside a retry-able pathway so retries collapse onto one
     logical write.
   - All balances in a bucket: `client.get_balances(bucket)`
   - One account's balance + holds: `client.get_account(bucket, account)`
   - Event history of a bucket: `client.list_events(bucket)`
   `bucket` is the project's own scope (e.g. `"orders"`,
   `"team:acme"`); `account` is whatever entity holds balance
   (e.g. `"user:alice"`, `"invoice:9821"`).

6) Do NOT:
   - hand-roll edge probing or retries against `/gateway/health` or
     `/gateway/edges` — the SDK does both, including 60-second
     cool-off and re-probe on `503`/`504`/timeout.
   - pin a single edge URL. The defaults (`use1`, `euc1`, `ape1`)
     rotate automatically by observed latency.
   - generate the idempotency nonce inside the retry loop. Capture
     it above the retry boundary so retries reuse the same nonce.
   - add a custom retry / circuit-breaker library on top — it fights
     the SDK's failover.

7) Verify. Run one write and one read with `SHARDD_API_KEY` set,
   confirm both return non-error. If the project has a test suite,
   add a single integration test gated on `SHARDD_API_KEY` being
   present (skip otherwise so CI without the secret still passes).

References:
- https://shardd.xyz/guide/quickstart    (operations in every language)
- https://shardd.xyz/guide/sdks          (package coordinates + failover behavior)
- https://shardd.xyz/guide/public-edge-clients (raw HTTPS fallback)
````

## What it does

- Detects the project's primary language by inspecting build files (`Cargo.toml`, `pyproject.toml`, `package.json`, `build.gradle.kts`).
- Installs the matching first-party SDK with the project's own package manager.
- Adds `SHARDD_API_KEY` to the project's existing env-var convention.
- Wires a single shared client and sketches the credit/debit/balance call sites.
- Skips manual edge probing and retry plumbing — the SDK already does that.

## Before you run it

1. Grab an API key at [app.shardd.xyz/dashboard/keys](https://app.shardd.xyz/dashboard/keys) and have it ready.
2. Have the project open in your agent's working tree.
3. After it runs, see the [Quickstart](/guide/quickstart) for the full per-language method surface and the [SDKs](/guide/sdks) page for package coordinates and failover details.

---

# Public Edge Clients

Source: https://shardd.xyz/guide/public-edge-clients

External developers do not join the private libp2p node mesh.

Instead, they use plain HTTPS against public edge gateways. The edges expose two
bootstrap endpoints:

- `GET /gateway/health`
- `GET /gateway/edges`

## `GET /gateway/health`

This is the cheap liveness and routing-hints endpoint for one edge.

Example fields:

- `edge_id`
- `region`
- `base_url`
- `ready`
- `healthy_nodes`
- `best_node_rtt_ms`
- `sync_gap`
- `overloaded`

## `GET /gateway/edges`

This returns the public regional edge directory only. It does not expose private
full-node addresses or internal mesh identities.

Example response:

```json
{
  "observed_at_unix_ms": 1775770123456,
  "edges": [
    {
      "edge_id": "use1",
      "region": "us-east-1",
      "base_url": "https://use1.api.shardd.xyz",
      "health_url": "https://use1.api.shardd.xyz/gateway/health",
      "reachable": true,
      "ready": true,
      "healthy_nodes": 3,
      "best_node_rtt_ms": 18,
      "sync_gap": 0,
      "overloaded": false
    }
  ]
}
```

## Official clients

The same bootstrap + failover dance is built into the official SDKs, so
typical apps call a couple of high-level methods and skip the plumbing:

::: code-group

```bash [curl]
# no install — curl ships with every system
```

```toml [rust]
# Cargo.toml
[dependencies]
shardd = "0.1"
```

```bash [python]
pip install shardd
```

```bash [typescript]
npm install @shardd/sdk
```

```kotlin [kotlin]
// build.gradle.kts
dependencies {
    implementation("xyz.shardd:sdk:0.1.0")
}
```

:::

- Rust → [crates.io/shardd](https://crates.io/crates/shardd) · [docs.rs](https://docs.rs/shardd)
- Python → [pypi.org/project/shardd](https://pypi.org/project/shardd/)
- TypeScript → [npmjs.com/package/@shardd/sdk](https://www.npmjs.com/package/@shardd/sdk)
- Kotlin / JVM → [central.sonatype.com/artifact/xyz.shardd/sdk](https://central.sonatype.com/artifact/xyz.shardd/sdk)
- Full source + runnable examples → [shardd-xyz/shardd/tree/main/sdks](https://github.com/shardd-xyz/shardd/tree/main/sdks)

Each SDK accepts a list of bootstrap edges, probes
`/gateway/health`, refreshes `/gateway/edges` on demand, and fails over
on timeout or `5xx`. See the [Quickstart](/guide/quickstart) for the
common calls.

---

# Architecture

Source: https://shardd.xyz/guide/architecture

`shardd` splits the system into two planes.

## Private state plane

- full nodes
- local Postgres per full node
- private libp2p mesh
- replication, sync, and convergence

These nodes are correctness-critical and should stay private.

## Public edge plane

- regional edge gateways
- public HTTPS
- developer API key auth
- public edge discovery
- full-node selection based on live mesh health

The edge gateway is not a dumb proxy. It participates in the private mesh
enough to maintain a live routing view, but it holds no shard state of its own.

## Why this is cleaner

- public developers do not need libp2p credentials
- full nodes do not become an internet-facing auth surface
- client tooling stays simple: HTTPS plus a bearer key
- routing decisions use live mesh state, not just DNS

## Deployment shape

Typical production layout:

- a few full-node regions
- more public edge regions than full-node regions
- one separate control-plane/dashboard host

Typical dev layout:

- 3 full nodes
- 3 public edges
- 1 dashboard host