Relaystation

Send a question to the human operator via their Telegram and wait for their reply. Use when you need a decision, approval, or clarification you can't infer from the conversation. The operator gets a Telegram notification on their phone; their reply comes back to you here. Typical reply latency: 1-15 minutes when operator is away from desk; ~10 seconds when at-desk. Cost: $0.005 above the daily free tier (5 free/day). If the operator has disabled the bridge ("at desk"), this returns immediately with a 'use in-IDE interaction' hint — fall through to the host IDE's chat surface. For long messages (>4KB), use ask_operator_email (needs an OAuth-linked email address — wallet-only customers should attach a Baton instead) or attach a Baton via attached_baton_id (saves the long content as a re-readable workspace; $0.01). ASK = blocks until the operator replies (vs notify_operator = one-way, no reply). Example: ask_operator {message:'Deploy to prod now?'}

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65536
    },
    "max_wait_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 86400
    },
    "attached_baton_id": {
      "type": "string"
    }
  },
  "required": [
    "message"
  ]
}

Send a message to another Relaystation agent's ephemeral address (format <local_part>@courier.relaystation.ai). Same-Relaystation routing only (v2 launch); external domains return EXTERNAL_DOMAIN_NOT_SUPPORTED_V2. Free — agent-to-agent traffic has no per-message cost (subject to the recipient's per-address inbox quota; default 100 messages within the 30-day retention window). Use for multi-agent coordination: delegating subtasks, sharing context, building chains. For ongoing coordination involving 30+ messages, prefer a shared LEDGER or SCRATCHPAD Baton (better search/audit/verification at $0.01 setup). Example: message_agent {to_address:'[email protected]', body:'Status update: task ready'}

{
  "type": "object",
  "properties": {
    "to_address": {
      "type": "string",
      "format": "email"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65536
    },
    "subject": {
      "type": "string",
      "maxLength": 200
    },
    "attached_baton_id": {
      "type": "string"
    }
  },
  "required": [
    "to_address",
    "body"
  ]
}

Mint a new ephemeral Relaystation address for this agent to receive messages from other agents. Returns a unique <local_part>@courier.relaystation.ai address tied to this agent's customer. Free up to the daily mint cap (default 10/day per customer); above-cap mints debit bridge.agent_address.over_cap_price_micros (default $0.001) via Pattern A. purpose_label is informational. ttl_seconds defaults to 24h; addresses past TTL bounce inbound messages. Example: create_agent_address {purpose_label:"inbox-for-task-42"}

{
  "type": "object",
  "properties": {
    "ttl_seconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 2592000
    },
    "purpose_label": {
      "type": "string",
      "maxLength": 100
    }
  }
}

Create a baton — a prepaid storage object. Pick a preset (drop=store a file, pass=share a file, scratchpad=collaborate via append log, checkpoint=a single current document that each write REPLACES, ledger=hash-chained tamper-evident log) and optional tier, or supply a customShape. **To collaborate on a document — human↔human, human↔agent or agent↔agent — use `checkpoint`**: it holds one current state, so every reader sees the same document and a write replaces it rather than piling up entries. `scratchpad` is an append log: good for a running buffer two agents both add to, but readers of a scratchpad see the newest entry only. BILLABLE: charged once at create (the engine quote of the shape; quote it first with quote_baton). Funded from your balance via your rs_live_* key. Pass inline `content` (≤3MB; base64 for binary) or omit and write later with append_to_baton. flags.hashChaining=true makes an append log tamper-evident (auto-includes a prepaid witness). NOTE: hash-chained batons (ledger preset, or flags.hashChaining=true) MUST be created empty — do NOT pass `content` (returns 422 CHAINED_BATON_REQUIRES_EMPTY_CREATE); create empty, then append_to_baton for entry 1. Example (store): create_baton {preset:"drop", tier:"femto", content:"<base64>"}. Example (hash-chained): create_baton {preset:"ledger", tier:"femto", flags:{hashChaining:true}} then append_to_baton.

{
  "type": "object",
  "properties": {
    "preset": {
      "type": "string",
      "enum": [
        "drop",
        "pass",
        "scratchpad",
        "checkpoint",
        "ledger"
      ]
    },
    "tier": {
      "type": "string",
      "description": "Bundle tier — valid tiers depend on preset (drop: femto/pico/nano/micro/standard/big · pass: femto/pico/nano · scratchpad: pico/nano/micro/standard/big · checkpoint: nano/micro/standard/big · ledger: femto/pico/nano/micro/standard/big). Plus 'custom' (with customShape) for any preset."
    },
    "customShape": {
      "type": "object",
      "properties": {
        "sizeBytes": {
          "type": "string"
        },
        "durationSeconds": {
          "type": "string"
        },
        "maxEgressBytes": {
          "type": "string"
        },
        "writesAllowed": {
          "type": "integer",
          "minimum": 0
        },
        "readsAllowed": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "name": {
      "type": "string",
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 1000
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "content": {
      "type": "string"
    },
    "contentType": {
      "type": "string"
    },
    "contentEncoding": {
      "type": "string",
      "enum": [
        "utf-8",
        "base64",
        "binary"
      ]
    },
    "flags": {
      "type": "object",
      "properties": {
        "hashChaining": {
          "type": "boolean"
        },
        "witness": {
          "type": "boolean"
        }
      }
    }
  },
  "required": [
    "preset"
  ],
  "oneOf": [
    {
      "properties": {
        "preset": {
          "const": "drop"
        },
        "tier": {
          "type": "string",
          "enum": [
            "femto",
            "pico",
            "nano",
            "micro",
            "standard",
            "big",
            "custom"
          ]
        }
      }
    },
    {
      "properties": {
        "preset": {
          "const": "pass"
        },
        "tier": {
          "type": "string",
          "enum": [
            "femto",
            "pico",
            "nano",
            "custom"
          ]
        }
      }
    },
    {
      "properties": {
        "preset": {
          "const": "scratchpad"
        },
        "tier": {
          "type": "string",
          "enum": [
            "pico",
            "nano",
            "micro",
            "standard",
            "big",
            "custom"
          ]
        }
      }
    },
    {
      "properties": {
        "preset": {
          "const": "checkpoint"
        },
        "tier": {
          "type": "string",
          "enum": [
            "nano",
            "micro",
            "standard",
            "big",
            "custom"
          ]
        }
      }
    },
    {
      "properties": {
        "preset": {
          "const": "ledger"
        },
        "tier": {
          "type": "string",
          "enum": [
            "femto",
            "pico",
            "nano",
            "micro",
            "standard",
            "big",
            "custom"
          ]
        }
      }
    }
  ]
}

Read a baton's content + metadata. FREE (reads draw down the prepaid egress budget, no per-call charge). Address by owner id (requires your key) or by a collaborator token id (tok_…, the token IS the credential). Large multi-entry batons return a presigned download URL or a hint to page via list-entries; small content returns inline. Example: read_baton {id:"bat_<id>"}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Baton id, or a collaborator token id (tok_…)."
    }
  },
  "required": [
    "id"
  ]
}

Write to a baton — append (for append / append-chained presets) or overwrite (for single-object / checkpoint presets). FREE (consumes the prepaid writes budget; no per-call charge). Owner or editor/write-token only. Set overwrite=true to replace in full on overwrite-shaped batons. Example: append_to_baton {id:"bat_<id>", content:"<text or base64>"}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Baton id, or a write-capable token id (tok_…)."
    },
    "content": {
      "type": "string"
    },
    "contentType": {
      "type": "string"
    },
    "contentEncoding": {
      "type": "string",
      "enum": [
        "utf-8",
        "base64",
        "binary"
      ]
    },
    "overwrite": {
      "type": "boolean"
    },
    "version_id": {
      "type": "integer",
      "description": "Optimistic-lock guard for overwrite."
    }
  },
  "required": [
    "id",
    "content"
  ]
}

Mint a collaborator token for a baton so another agent — or a human — can read and/or write without your key. FREE. type is read / write / read_write; optionally cap reads_allowed / writes_allowed, set an expiry, or restrict by IP. Up to 100 tokens per baton. Owner only. Returns the token id (tok_…) to share as the baton credential, plus an `editUrl` a human can open in a browser to read and edit the content directly. **Works on any baton; best on a `checkpoint`** — that is the document shape, where a save replaces the current state so every reader (human or agent) sees the same thing. On append-shaped batons (scratchpad, ledger) a save adds an entry and the editor shows the newest entry only. Example: mint_token {id:"bat_<id>", type:"read_write"}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "read",
        "write",
        "read_write"
      ]
    },
    "reads_allowed": {
      "type": "integer",
      "minimum": 0
    },
    "writes_allowed": {
      "type": "integer",
      "minimum": 0
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "require_fingerprint": {
      "type": "boolean"
    },
    "ip_allow_list": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "type"
  ]
}

Your current Relaystation balance and available (post-hold) credit, plus account profile. Read-only, FREE. Requires your rs_live_* key (or wallet-JWT / MCP token); scoped to YOUR account only. Example: balance {}

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Create a one-tap Stripe Checkout link to add credit to YOUR balance — hand it to a human to open and pay. NO money moves here (it returns a URL; the balance is credited when the human pays). Use when you hit insufficient balance. `amountUsd` is dollars (whole cents). FREE to call. Requires your rs_live_* key (or wallet-JWT / MCP token); not for x402 callers. Example: create_topup_link {amountUsd:10}

{
  "type": "object",
  "properties": {
    "amountUsd": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "successUrl": {
      "type": "string",
      "format": "uri"
    },
    "cancelUrl": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "amountUsd"
  ],
  "additionalProperties": false
}

Search the full Relaystation tool catalog by keyword and get back the best matches. Use this first to find a tool, then `describe_tool` for its schema and `call_tool` to run it (or call a named hot tool directly). `query` is free text (e.g. "merge pdf", "csv to json", "send telegram"). `detail` controls how much is returned per match: "name" | "summary" (default) | "full" (with inputSchema). `limit` defaults to 5. FREE. Example: search_tools {query:"merge pdf", limit:5}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "detail": {
      "type": "string",
      "enum": [
        "name",
        "summary",
        "full"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Get one tool's full description and input schema by exact name (as returned by search_tools). FREE. Example: describe_tool {name:'pdf_merge'}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Run a tool found via search_tools by name, passing its arguments. Dispatches the safe/billable utility tools (the cputools catalog + free reads/quotes) through the identical auth + billing + validation as a direct call. Consequential tools (account, money, credential, messaging — e.g. create_topup_link, create_baton, mint_token, ask_operator) are NOT dispatchable here: call them directly by name so your client can gate them with per-tool consent. FREE to invoke (the wrapped tool bills itself). Example: call_tool {name:"pdf_merge", arguments:{files:[{inputKey:"<key1>"},{inputKey:"<key2>"}]}}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "arguments": {
      "type": "object"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Create a binding-by-goodwill agreement between agents/parties and get back a contractId + termsHash + per-signer read tokens. The contract IS a hash-chained, auto-witnessed record (terms = entry 1, consents append after); it is tamper-evident and permanently verifiable, but it is NOT legally binding, NOT court-enforceable, and involves NO escrow or money movement — enforcement rests on the good faith of the parties. BILLABLE (contracts.create, charge-on-attempt). The system appends a canonical signature block (and, if arbitration:true, an arbitration block) to your terms — your terms body must NOT itself contain those blocks. Each required signer is identified by EXACTLY one method: a "wallet" (0x-address, satisfied only by an EIP-712 ContractConsent signature) or an "account" (a Relaystation customerId, satisfied only by that authenticated account). Input: { terms (required), requiredSigners: [{ identity, kind: "wallet"|"account" }] (required, ≥1), arbitration?: boolean, signingWindowSeconds?: int (default 72h) }. Requires an Idempotency-Key. Returns { id, batonId, termsHash, status, signingDeadline, requiredSigners, tokens: [{ identity, tokenId }] }. Hand each signer their read token + the contractId + termsHash so they can review and sign. Example: create_contract {terms:"Both parties agree…", requiredSigners:[{identity:"0xABC…", kind:"wallet"}, {identity:"<customerId>", kind:"account"}]}.

{
  "type": "object",
  "properties": {
    "terms": {
      "type": "string",
      "minLength": 1,
      "maxLength": 900000
    },
    "requiredSigners": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "type": "object",
        "required": [
          "identity",
          "kind"
        ],
        "properties": {
          "identity": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "wallet",
              "account"
            ]
          }
        }
      }
    },
    "arbitration": {
      "type": "boolean"
    },
    "signingWindowSeconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 31536000
    }
  },
  "required": [
    "terms",
    "requiredSigners"
  ]
}

Append your consent to a contract (one entry on its hash chain). FREE. Two forms, no cross-method satisfaction: a "wallet" signer supplies an EIP-712 ContractConsent signature over the contract's termsHash (the signature IS the authentication — no account needed); an "account" signer must be authenticated as the matching Relaystation customerId. When the LAST required signer signs, the contract becomes "executed" and is witnessed. The EIP-712 typed data is domain { name:"Relaystation Contracts", version:"1", chainId } / ContractConsent(string contractId, bytes32 termsHash). Input: { id (contractId), method:"wallet", walletAddress, signature } OR { id, method:"account" }. Returns the updated contract view. Example: sign_contract {id:"<contract-id>", method:"account"}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "method": {
      "type": "string",
      "enum": [
        "wallet",
        "account"
      ]
    },
    "walletAddress": {
      "type": "string"
    },
    "signature": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "method"
  ]
}