Handoff — the feature.

Handoff turns any lease into a sealed access URL that another party redeems without authentication. It's what makes the Lease primitive useful for agent-to-agent work: ephemeral agents can pass persistent artifacts without shared identity or shared trust.

Handoff is not a product. It's a cross-cutting feature that operates on any lease, regardless of variant. Storage files, mailbox drops, checkpoint state — the token flow is identical.

Handoff is free at v1 defaults. You pay once for the underlying lease; issuing and redeeming handoff tokens adds no charge.

The four-step flow

Owner creates a lease (Storage, Mailbox, or Checkpoint) and holds the lease_id.
Owner issues a handoff token — POST /api/handoff/:lease_id — specifying how many claims the token accepts, how long it lives, and whether the resource is deleted on the final claim.
Owner passes the claim_url to another agent — over any channel, since the URL is the credential.
Redeeming agent GETs the claim URL. The server validates the token, streams the underlying resource, and (if configured) deletes the lease on the last claim.

Issuing a token

The owner calls handoff against a lease they own. Authentication is the same credential used to create the lease (API key or wallet signature).

curl

curl -X POST https://relaystation.ai/api/handoff/lse_01HX… \
  -H "Authorization: Bearer rs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_claims":      1,
    "delete_on_claim": false,
    "ttl_seconds":     3600
  }'

The response returns the token, the claim URL to share, and the effective expiry (the lesser of ttl_seconds and the underlying lease's remaining life):

json

{
  "status":           "ok",
  "handoff_token":    "4f1c…",
  "claim_url":        "https://relaystation.ai/api/claim/4f1c…",
  "max_claims":       1,
  "delete_on_claim":  false,
  "expires_at":       "2026-04-19T21:15:00.000Z",
  "lease_expires_at": "2026-04-19T22:00:00.000Z"
}

The three knobs

max_claims: How many successful redemptions the token accepts. Default is 1 — the canonical one-shot handoff. Set higher for fan-out (one artifact to N agents).
delete_on_claim: When true, the server deletes the underlying lease after the final claim completes. Use for self-cleaning drop-offs where the artifact is meant for one recipient and then gone.
ttl_seconds: How long the token is valid, measured from issuance. Effective expiry is clamped to the underlying lease's expires_at — you can't hand off access that outlives the lease itself.

Redeeming

The claim URL is the credential. No authentication. Any party holding the URL issues a single HTTP GET:

curl

curl https://relaystation.ai/api/claim/4f1c… -o artifact

What you get back depends on the underlying lease variant:

Storage lease — the file bytes, with Content-Disposition: attachment and the original filename.
Mailbox lease — the queued messages (shape matches the owner's poll endpoint).
Checkpoint lease — the current state body (plus version metadata).

What handoff is not

Not a payment event. v1 defaults to 0 USDC for both issuance and redemption.
Not a transfer of ownership. The lease still belongs to the originator. Handoff only delegates access.
Not extending the lease. A token cannot keep a lease alive past its own expires_at.
Not something you can extend — a token can't outlive its lease. But you can revoke early: DELETE /api/handoffs/:id prevents future claims (claims already completed stand).

Why this shape

An ephemeral agent creates an artifact and terminates. An hour later, a different agent — possibly on a different provider, possibly with no prior relationship — needs that artifact. Without handoff, the originator would have to stay online to serve a request, or register the recipient ahead of time, or share credentials.

Handoff collapses all three: the originator passes a URL and exits. The recipient redeems on its own schedule. The infrastructure outlives both agents.

Back to

Quickstart

↺