# Batons

A baton is the core object in Relaystation: a prepaid storage object you stash through the API and act on later. It can hold any kind of content — text, CSV, or a binary file. Most batons carry text, because most of what agents and developers hand off to each other is text.

You configure a baton along **five independent groups**. Pick the values that fit your use, pay once at create, and draw down the prepaid quotas until it expires. There are no monthly fees and no per-use charges after create.

## The five groups

1. **Write behavior** — one of four:
   - **Single object** — stores one file, image, video, or binary payload. Replace it any time; delete it when done.
   - **Append** — a text log you add entries to over time.
   - **Append, hash-chained** — an append log where each entry is hash-linked to the previous, so tampering is detectable. Auto-includes a document-witness.
   - **Overwrite** — a text file you replace in full; only the latest is kept.
2. **Capacity** — size (storage), duration (validity), and egress (the read budget). A single write over 3 MB uploads via a presigned URL the create call returns.
3. **Sharing** — collaborator tokens. Up to 100 per baton; each token carries a scope (`read` / `write` / `read_write`), an optional read cap, and an optional expiry.
4. **Lifecycle** — burn-after-reading (delete the baton once every token's read cap is consumed) and disposal (a soft delete with a grace period, or a hard delete).
5. **Trust** — the document-witness. When enabled, Relaystation cryptographically signs the baton's content hash and keeps the signed record for seven years; you verify it offline against Relaystation's published key. See [Trust](/docs/trust).

Every value in every group is configurable at create, and several can be changed afterward. A baton is not a fixed type — it is the values you choose.

## Preconfigs — fast-start prefills

Five named preconfigs set the five-group values to common shapes, so you can start from a sensible default instead of filling in every field. They are starting points, **not** the organizing principle — every value remains yours to change on create.

| Preconfig | Use case | Sets up |
|---|---|---|
| **Drop** | Store a file. | Single object; multi-read until expiry. |
| **Pass** | Share a file. | Single object plus a read-capped token; burns once the token is consumed. |
| **Scratchpad** | Collaborate. | Append log; tokens for collaborators. |
| **Checkpoint** | Save state. | Overwrite; replace the snapshot as you go. |
| **Ledger** | Audited ledger. | Append, hash-chained; tamper-evident; auto-witnessed. |

## What you can do with a baton

The five groups map onto the operations a baton supports, each enabled at creation or switched on afterward:

1. **Read** the content, fully or partially.
2. **Write** to it — append for an append log, replace for an overwrite baton.
3. **Share** — issue tokens that grant read or write access to others.
4. **Seal** — hash, sign, and verify the content, by entry or as a whole (the trust group).
5. **Delete** — schedule or force removal.
6. **Extend** — add time, size, or read allowance before a limit is hit.

## Pricing

One engine-computed quote is the published price. Quote any shape ahead of time with `POST /v1/baton/quote`; create it with `POST /v1/baton`. The price is the engine quote of the shape you chose — keyed off the real costs of **storage** and **egress** (API calls and metadata lookups are absorbed into the margin on those) — and it is **frozen at create** for that baton. There are no catalog prices and no tiers sold as priced SKUs; a named preconfig is priced exactly like any custom shape. The document-witness and chained-hash trust features are priced into the quote when enabled. Every billable order is charged at least the network minimum, a fraction of a cent per call. See [Pricing](/pricing) and the live calculator.

## Lifecycle

A baton lives until it hits a limit — its time, size, or read allowance. At that point it transitions toward deletion: first a tombstone (a recoverable soft-delete window), then a hard delete. You can extend any dimension before then, or schedule a delete yourself.