Operate
On-chain tools
Give your apps a reliable RPC endpoint, a signing key that never leaves CLI, and calls when blocks arrive or contracts emit events.
Apps that use a blockchain need a reliable connection to it, a way to sign transactions safely, and a way to react to what happens on chain. CLI gives each project all three, so your app never holds a private key.
How to use it: in project settings, open Signers and RPC to get a reliable chain connection and a managed wallet with limits (which contracts, how much per day). Add Watchers on an app to react to on-chain events, and Keepers in project settings for scheduled jobs.
Apps that talk to a blockchain usually need three things: an RPC endpoint that stays up, a key to sign transactions, and a way to react to what happens on chain. CLI provides all three per project, so your app never has to hold a private key.
RPC with failover
Each project gets one RPC address per chain. Behind it, CLI tries the platform's providers for that chain in turn, sets aside one that just failed for a while, and caches a few answers that rarely change (such as the chain id) for a short time.
Which chains are available
With the API:
GET /v1/chainsThis lists the chain ids the platform has RPC providers for.
Send a request
The endpoint takes standard JSON-RPC, one request or a batch of up to 50.
With the API:
POST /v1/projects/:id/rpc/8453
{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}People and agents use their normal token. Your apps can use any of the project's signer tokens (see below), so you don't need to give an app a personal token.
Only read methods and raw broadcasts are allowed: eth_blockNumber, eth_chainId, eth_call, eth_estimateGas, eth_gasPrice, eth_maxPriorityFeePerGas, eth_feeHistory, eth_getBalance, eth_getCode, eth_getStorageAt, eth_getTransactionCount, eth_getTransactionByHash, eth_getTransactionReceipt, eth_getBlockByNumber, eth_getBlockByHash, eth_getLogs, eth_sendRawTransaction, eth_syncing, net_version and web3_clientVersion. Anything that asks the node to sign is refused.
Managed signers
A managed signer is a key CLI creates and keeps for your project. The private key is sealed with your project's key and never leaves CLI. Your app uses a signer token to ask CLI to sign or send a transaction, and CLI checks each request against the signer's policy first. Every signature is logged.
Create a signer
Creating a signer takes an admin, and a person with a second factor is asked to confirm it.
With the API:
POST /v1/projects/:id/signers
{
"name": "payouts",
"policy": {
"chains": [8453],
"contracts": ["0x…"],
"selectors": ["0xa9059cbb"],
"maxValuePerTx": "0",
"maxValuePerDay": "0",
"perMinute": 30
}
}The answer includes the signer's address, its token (shown once), and the variables to give your app:
| Variable | Value |
|---|---|
CLI_SIGNER_URL | <api>/v1/signers/<id> |
CLI_SIGNER_TOKEN | The signer token |
CLI_RPC_URL | <api>/v1/projects/<id>/rpc/<chainId> |
Store the token as a secret variable on your app (see /docs/configuration).
Policy rules
| Field | Meaning | Default |
|---|---|---|
chains | Chain ids it may sign for (at least one) | Required |
contracts | Contract addresses it may call; empty means any | Any |
selectors | Function selectors it may call; empty means any | Any |
maxValuePerTx | Most native value (in wei) per transaction | 0 (no value) |
maxValuePerDay | Most native value (in wei) per day | 0 (no value) |
perMinute | Most signatures per minute (1 to 600) | 30 |
allowDeploy | May it deploy contracts (a transaction with no to) | false |
allowMessages | May it sign plain messages | false |
A transaction the policy doesn't allow is refused with SIGNER_POLICY, and the message names the rule (for example "isn't one of the contracts this signer may call"). Nothing is signed. If the transaction is right, an admin changes the policy; agents are told never to try to work around it.
Use a signer from your app
All of these use Authorization: Bearer $CLI_SIGNER_TOKEN.
| Request | What it does |
|---|---|
GET /v1/signers/:id/address | The signer's address |
POST /v1/signers/:id/send {"tx": {"to", "data", "chainId", "value"?}} | Fills in nonce, gas and fees from the chain, signs and broadcasts |
POST /v1/signers/:id/sign {"tx": {…}} | Signs a transaction you've filled in, without sending it |
POST /v1/signers/:id/sign-message {"message"} | Signs a message (only with allowMessages) |
POST /v1/signers/:id/send
Authorization: Bearer $CLI_SIGNER_TOKEN
{"tx": {"to": "0x…", "data": "0xa9059cbb…", "chainId": 8453}}Manage signers
| Request | What it does | Who |
|---|---|---|
GET /v1/projects/:id/signers | List signers | Any member |
GET /v1/signers/:id/log | The signing log | Any member |
PATCH /v1/signers/:id {"policy"?, "paused"?} | Change the policy, or pause it | Admin |
POST /v1/signers/:id/rotate-token | Issue a new token (the old one stops working) | Admin |
DELETE /v1/signers/:id | Delete the signer | Admin |
A paused signer refuses everything with SIGNER_POLICY.
Chain watchers
A watcher calls an endpoint on your app when something happens on chain: every Nth block, or when a contract emits an event. Adding one needs the developer role.
Watch for events
With the API:
POST /v1/services/:id/watchers
{"chainId": 8453, "kind": "event", "address": "0x…", "topics": ["0x…"], "path": "/hooks/transfer"}topics is optional (up to 4, each a 32-byte hex value).
Watch blocks
With the API:
POST /v1/services/:id/watchers
{"chainId": 8453, "kind": "block", "everyBlocks": 10, "path": "/hooks/block"}Check the signature
CLI POSTs JSON to the path on your app. Each call carries X-CLI-Signature: t=<ms>,v1=<hex>, where v1 is HMAC-SHA256 with the watcher's secret over `${t}.${body}`. The secret is returned once, when you create the watcher. Check the signature before trusting a call, and reject old timestamps.
GET /v1/services/:id/watchers lists a service's watchers and DELETE /v1/watchers/:id removes one.
Decode events, keep a table of them, or run a job
Give the event's ABI and CLI decodes each log (numbers come as decimal strings, so nothing loses precision) and fills in the topic for you. Then choose what happens with the events:
target | What happens |
|---|---|
webhook (default) | CLI calls path on your app, signed, with logs and the decoded events |
index | The decoded events are written into one of the project's Postgres databases, in indexTable (created if needed: chain_id, block_number, tx_hash, log_index, address, event, args as JSONB). Rows already there are skipped, so a retried range never doubles up |
job | command runs in the app's live image with the events in CLI_EVENTS (JSON), plus CLI_FROM_BLOCK and CLI_TO_BLOCK |
POST /v1/services/:id/watchers
{"chainId": 8453, "kind": "event", "address": "0x…", "abi": "event Deposit(address indexed user, uint256 amount)",
"target": "index", "indexDatabaseId": "svc_…", "indexTable": "deposits", "fromBlock": 18000000}fromBlock backfills from a past block, 500 blocks at a time. If a delivery, insert or job fails, the same range is tried again on the next check. Agents can do this with cli_watch_contract.
Keepers
To call a contract on a schedule or when an event happens, without running an app for it, see Keepers.
Related
- Teams and security for on-chain receipts of your audit log.
- The CLI token for paying for hosting with the CLI token on Robinhood Chain.
- Error codes for
SIGNER_POLICYand other codes.