Write Endpoints
All paths are relative to https://api.clocktower.finance.
All write endpoints use POST. The server returns unsigned transactions — you sign and broadcast from your wallet. The server never relays signed transactions.
Prepare, readiness, and POST /transactions/status accept optional ?chainId= (query string, not JSON body). Simulation and gas estimation run on the selected chain. See Chain selection.
Prepare response format
Full prepare responses include:
| Field | Description |
|---|---|
requestId | Correlation UUID for support (not stored server-side) |
instructions | Ordered steps for signing and broadcasting |
warnings | Non-fatal hints (e.g. remit may need multiple txs) |
unsignedTransactions | Calldata: to, data, value, chainId, from |
signingMode | raw (single tx) or eip5792 (multi-tx batch) |
eip5792 | Batch descriptor when signingMode is eip5792 |
simulation | On-chain simulation results. Failed simulation returns an error before unsigned transactions are returned |
chainId | Selected REST chain (default 8453) |
gasEstimates | Per-tx gas budget on the selected chain |
gasSummary | Aggregated totals; remit backlogs include backlogMultiplier |
preflight | Operation-specific context |
Optional request fields
On prepare endpoints:
readinessOnly: true— preflight only; no unsigned transactions or gas estimatessimulateFromAddress— address foreth_estimateGaswhen signing wallet differs from broadcasterinfiniteApproval: true— on subscribe, request max ERC-20 allowance instead of amount-scoped approve
Preferred by-id routes
When you already have a subscription id, prefer id-only endpoints (chain is source of truth for amount/token/provider):
| Endpoint | Description |
|---|---|
POST /check_subscribe_readiness_by_id | Readiness with from + id |
POST /prepare/subscribe_by_id | Prepare subscribe with from + id |
POST /prepare/cancel_subscription_by_id | Provider cancel with from + id |
POST /prepare/unsubscribe_by_id | Subscriber unsubscribe with from + id |
POST /prepare/unsubscribe_by_provider_by_id | Provider remove with from + id + subscriber |
Endpoints
POST /prepare/* plus POST /check_subscribe_readiness and POST /check_remit_readiness share the write rate bucket (RPM + write daily). REST POST /check_subscribe_readiness_by_id uses the cheap/global bucket; the MCP tool of the same name uses the write/readiness bucket. Defaults:
| Lane | Write RPM | Write / prepare daily |
|---|---|---|
| Free | 2/min | 20/day |
| Developer | 5/min | 100/day |
| Endpoint | Description |
|---|---|
POST /check_subscribe_readiness | Validate whether an account can subscribe (object form) |
POST /check_subscribe_readiness_by_id | Same by id (preferred when id known) |
POST /prepare/create_subscription | Prepare a new subscription (amount = human token string, e.g. "10") |
POST /prepare/subscribe | Prepare subscribe (object form; includes ERC-20 approve when needed) |
POST /prepare/subscribe_by_id | Prepare subscribe by id (preferred) |
POST /prepare/cancel_subscription | Provider cancel |
POST /prepare/cancel_subscription_by_id | Provider cancel by id (preferred) |
POST /prepare/unsubscribe | Subscriber unsubscribe |
POST /prepare/unsubscribe_by_id | Subscriber unsubscribe by id (preferred) |
POST /prepare/unsubscribe_by_provider | Provider-initiated unsubscribe |
POST /prepare/unsubscribe_by_provider_by_id | Provider-initiated by id (preferred) |
POST /prepare/edit_details | Provider metadata edit |
POST /check_remit_readiness | Multi-day scan before remit() |
POST /prepare/remit | Prepare permissionless remit() |
POST /transactions/status | Poll confirmation after broadcast ({ "txHash": "0x…" }) |
See Rate limits.
Remit flow
check_remit_readiness → prepare_remit → sign → broadcast → repeat until caught up
One remit() clears at most maxRemits payments per transaction. Use get_subscriptions_due for a lightweight single-day read; use check_remit_readiness before preparing remit.