Your first lease in five minutes.

In this walkthrough, your agent pays once for a Storage lease, uploads a file, reads it back, and hands it off to another agent. Everything you learn here applies one-for-one to Mailbox and Checkpoint leases — same primitive, different configuration.

A lease is a resource you configure, pay for once, and walk away from. When it expires, the resource is physically deleted. While it's active, nothing else needs to happen.

1. Pick an auth path

RelayStation accepts two kinds of credentials for lease creation. You can use either — both produce the same lease, owned by the same actor. Pick the one that fits your agent.

API key

A prepaid balance under your account. Use Authorization: Bearer rs_live_…. Get a key from the dashboard. Best for long-running agents with a top-up flow.

x402 wallet

Pay in USDC on Base per request. Use the X-Payment header produced by an x402 client. Wallet address is the actor. Best for ephemeral agents with no prior relationship to RelayStation.

2. Issue a Storage lease

Send the bytes as the request body. Size, duration, and filename ride in headers so the server can price + write in one pass. The example below leases a 1 MB file for one hour.

API key path:

curl

# 1 MB file, 1 hour, paid from your prepaid balance
curl -X POST https://relaystation.ai/api/store \
  -H "Authorization: Bearer rs_live_YOUR_KEY" \
  -H "X-File-Name: notes.txt" \
  -H "X-Size-Bytes: 1048576" \
  -H "X-Duration-Seconds: 3600" \
  -H "Content-Type: text/plain" \
  --data-binary @notes.txt

x402 wallet path:

curl

# Same request, paid in USDC on Base via x402
curl -X POST https://relaystation.ai/api/store \
  -H "X-Payment: <x402-client-generated>" \
  -H "X-File-Name: notes.txt" \
  -H "X-Size-Bytes: 1048576" \
  -H "X-Duration-Seconds: 3600" \
  -H "Content-Type: text/plain" \
  --data-binary @notes.txt

Either path returns the same lease shape:

json

{
  "status":           "ok",
  "lease_id":         "lse_01HX…",
  "expires_at":       "2026-04-19T21:15:00.000Z",
  "duration_seconds": 3600,
  "duration_human":   "1.0 hour",
  "size_bytes":       1048576,
  "paid_usdc":        0.000029
}

The lease is live. The file is in S3, the countdown has started, and when expires_at passes, the bytes are physically deleted. That's the whole commitment.

3. Read it back

As the lease owner, you can download the file any number of times before expiry. Authenticate with the same credential you used to create it:

curl

curl https://relaystation.ai/api/download/lse_01HX… \
  -H "Authorization: Bearer rs_live_YOUR_KEY" \
  -o notes.txt

4. Hand it off (optional)

Another agent needs the file but isn't authenticated against your account. Issue a handoff token — a sealed, one-time-by-default URL that any party can redeem without auth:

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, "ttl_seconds": 3600}'

json

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

Give the claim_url to the other agent. It's just a URL — drop it into a message, a workflow input, a CLI arg. The redeeming agent does GET and gets the file. Handoff is free at v1 defaults; you pay only for the underlying lease.

5. That's it.

No subscription, no portal, no cleanup cron. The lease expires on its own. If the agent that created it terminated five minutes ago, none of this changes. The infrastructure outlives the agent.

Leases — the primitive

→