Agents API, SDK and MCP
An agent with a wallet can rent a server, use it and stop it without a human. There is no API key and no account: the wallet that owns the lease is the credential.
HTTP API
Base URL https://www.noracloud.xyz/api/v1. Every answer is JSON. Write calls on a lease (boot, exec, stop) need proof that the caller owns it.
| Endpoint | Auth | What it does |
|---|---|---|
| GET /plans | none | Sizes, prices read from the contract, templates and regions. |
| GET /quote?size=nano&seconds=600&wallet=0x… | none | The hourly price for that wallet and the USDG that open() will pull. |
| POST /leases/open | none | Body {size, seconds, wallet}. Returns {transactions: [{to, data, value, description}]}: the USDG approve if the allowance is short, then open(). Sign and send them in order. |
| POST /auth | signature | Body {message, signature}. Returns {token, expiresAt}. The token is valid 12 hours. |
| POST /leases/{id}/boot | owner | Body {template, region, image?, port?, command?, env?, sshKey?}. Creates the server. Returns {app, url, status}. |
| GET /leases/{id} | none | The lease as the chain sees it, plus the server status. |
| POST /leases/{id}/exec | owner | Body {command, cwd?, timeout?}. Runs a command on the server. Returns {stdout, stderr, exitCode, cwd}. |
| POST /leases/{id}/stop | owner | Returns {transaction}: the close() calldata. Once close() is on-chain, the same call deletes the server at once. |
| GET /wallets/{address}/leases | none | Every lease of a wallet with its state. |
| GET /status | none | {block, liveServers, ok}. |
Wallet signature
Sign this exact message with EIP-191 (personal_sign). The address is lowercase, the time is in unix seconds and the signature is valid for 5 minutes. Lease: all covers every lease of the wallet.
Nora Cloud
Wallet: 0xyouraddressinlowercase
Lease: 42
Time: 1795102435Either exchange it once for a token (POST /auth, then Authorization: Bearer <token>), or send it with every call in three headers: x-nora-wallet, x-nora-time and x-nora-signature, with the lease id of the URL in the message.
The whole flow with curl
# 1. the transactions to sign (approve if needed, then open)
curl -s -X POST https://www.noracloud.xyz/api/v1/leases/open -H 'content-type: application/json' \
-d '{"size":"nano","seconds":600,"wallet":"0xYourWallet"}'
# 2. sign and send them with your wallet, read the lease id from the LeaseOpened event
# 3. boot it (token from POST /auth)
curl -s -X POST https://www.noracloud.xyz/api/v1/leases/42/boot -H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"template":"node","region":"iad","env":{"MODE":"prod"}}'
# 4. run a command
curl -s -X POST https://www.noracloud.xyz/api/v1/leases/42/exec -H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"command":"uname -a"}'
# 5. stop: send the close() it returns, then call stop again to delete the server now
curl -s -X POST https://www.noracloud.xyz/api/v1/leases/42/stop -H "authorization: Bearer $TOKEN"SDK
One file for Node 20 or newer, served by this site. It holds the HTTP client, a small wallet signer, a CLI and the MCP server. Your key never leaves the process: it signs the transactions and the auth message locally.
curl -O https://www.noracloud.xyz/sdk/nora.mjsimport { Nora } from "./nora.mjs";
const nora = new Nora({ privateKey: process.env.NORA_KEY });
const box = await nora.rent({ size: "nano", template: "ubuntu", minutes: 10 });
console.log(await box.exec("uname -a"));
await box.stop(); // close() on-chain, server deleted, refund settled by the keeperCLI
NORA_KEY=0x... node nora.mjs plans
NORA_KEY=0x... node nora.mjs rent --size nano --template node --minutes 30
NORA_KEY=0x... node nora.mjs exec 42 "node -v"
NORA_KEY=0x... node nora.mjs status 42
NORA_KEY=0x... node nora.mjs stop 42The key needs a little ETH on Robinhood Chain for gas and the USDG for the lease.
MCP server
node nora.mjs mcp runs a local MCP server over stdio. It signs with NORA_KEY and exposes five tools: list_plans, rent_server, exec, server_status and stop_server. Add it to Claude Desktop, Claude Code or any MCP client:
{
"mcpServers": {
"nora": {
"command": "node",
"args": ["/path/to/nora.mjs", "mcp"],
"env": { "NORA_KEY": "0x..." }
}
}
}Give the agent a key that holds only what it may spend. The contract caps it at three live servers, and every lease is bounded by the USDG it prepaid.
