From 6555b3697585cc5ab4b890bf358e810af58155b3 Mon Sep 17 00:00:00 2001 From: Sahil Aujla Date: Thu, 14 May 2026 14:23:45 -0400 Subject: [PATCH] feat: add alchemy skill (RPC, Account Kit, Bundler, Gas Manager) Adds an `alchemy/` skill for the Alchemy surfaces that support Monad mainnet today: - Monad mainnet JSON-RPC endpoint and common method examples - Account Kit / Modular Account v2 for ERC-4337 smart accounts; primary use case is the agent-controlled wallet for deploying contracts and onchain actions (alternative to Safe multisig) - Bundler integration on Monad - Gas Manager (paymaster) policies for sponsored transactions Three entrypoints are documented in the SKILL.md: CLI, MCP, API key. The x402 / MPP agentic-gateway path is not currently confirmed on Monad mainnet and is omitted. Routing back to monskills: - Monad concepts (async exec, EIP-7702, block states) -> concepts/ - gas_limit pricing rules -> gas/ - Canonical ERC-4337 EntryPoint v0.6 / v0.7 addresses -> addresses/ - Historical on-chain data (Alchemy's data APIs don't support Monad mainnet yet) -> indexer/ - EOA + Safe multisig agent wallet -> wallet/ Updates `.claude-plugin/plugin.json` and root SKILL.md routing table to register the new skill. Co-authored-by: Cursor --- .claude-plugin/plugin.json | 3 +- SKILL.md | 7 ++ alchemy/SKILL.md | 87 +++++++++++++++++++++ alchemy/references/account-kit.md | 126 ++++++++++++++++++++++++++++++ alchemy/references/gas-manager.md | 89 +++++++++++++++++++++ alchemy/references/json-rpc.md | 122 +++++++++++++++++++++++++++++ 6 files changed, 433 insertions(+), 1 deletion(-) create mode 100644 alchemy/SKILL.md create mode 100644 alchemy/references/account-kit.md create mode 100644 alchemy/references/gas-manager.md create mode 100644 alchemy/references/json-rpc.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 60a9783..309ce24 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -20,6 +20,7 @@ "./gas", "./tooling-and-infra", "./feedback", - "./indexer" + "./indexer", + "./alchemy" ] } diff --git a/SKILL.md b/SKILL.md index 1fad510..908c90c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -22,6 +22,7 @@ This file will guide to the right skill with the latest knowledge about Monad an | Understanding gas pricing on Monad | `gas/` | | Checking if a tooling/infra provider supports Monad | `tooling-and-infra/` | | Adding a historical/activity feed or any feature that requires indexing onchain smart contract events | `indexer/` | +| Setting up Alchemy as the Monad RPC provider, or building an ERC-4337 smart-account agent wallet on Monad with sponsored gas (Gas Manager / Account Kit / Bundler) | `alchemy/` | | Reporting that monskills got you stuck, hit the same error, or the user is complaining about monskills | `feedback/` | ## Skills @@ -79,6 +80,12 @@ This file will guide to the right skill with the latest knowledge about Monad an - Prereqs: `npm install -g envio-cloud` + `envio-cloud login`. The monskills hook gates `envio-cloud` commands until both are satisfied. - Never install the CLI or run `login` on the user's behalf — surface the prompt and wait. +### [Alchemy](/alchemy/SKILL.md) +- Use Alchemy for Monad mainnet **JSON-RPC**, **Account Kit** (ERC-4337 smart accounts), **Bundler**, and **Gas Manager** (paymaster for sponsored transactions). +- Pair with `gas/` — sponsored ops still pay the policy owner for `gas_limit`, not `gas_used`. Tight estimates matter. +- Alchemy's Token / NFT / Prices / Portfolio / Transfers / Simulation / Webhook APIs do **NOT** yet support Monad mainnet — for on-chain data, use `indexer/`. +- Authored by Alchemy under MIT. + ### [Feedback](/feedback/SKILL.md) - Anonymous feedback pipeline for agents using monskills. - Fetch when the agent is stuck, hitting the same error repeatedly, or the user is complaining about monskills. diff --git a/alchemy/SKILL.md b/alchemy/SKILL.md new file mode 100644 index 0000000..f74e9fb --- /dev/null +++ b/alchemy/SKILL.md @@ -0,0 +1,87 @@ +--- +name: alchemy +description: Use Alchemy for the parts of building on Monad that Alchemy supports today — Monad mainnet **JSON-RPC**, **Account Kit** (ERC-4337 smart accounts for agent wallets), **Bundler**, and **Gas Manager** (paymaster for sponsored transactions). Fetch this skill when the agent needs an RPC endpoint, needs to set up an AA agent wallet with a smart account, or needs to sponsor gas. Pair it with monskills' `gas/` for Monad-specific `gas_limit` pricing rules, `concepts/` for async execution caveats, and `addresses/` for canonical ERC-4337 EntryPoint addresses. Alchemy's Token / NFT / Prices / Portfolio / Transfers APIs do **NOT** support Monad yet — for on-chain data, fetch `indexer/` (HyperIndex on Envio Cloud) instead. +--- + +# Alchemy on Monad + +Alchemy's developer platform supports Monad mainnet for **standard EVM JSON-RPC** and **Account Abstraction** (Account Kit, Bundler, Gas Manager). This skill points agents at the right Alchemy entrypoint for each use case on Monad. + +> **What Alchemy does NOT yet support on Monad:** Token API, NFT API, Prices API, Portfolio API, Transfers API, Simulation API, Webhooks. For on-chain data on Monad use the [`indexer/`](../indexer/SKILL.md) skill (HyperIndex on Envio Cloud). For Monad-specific gas pricing rules use [`gas/`](../gas/SKILL.md). For canonical ERC-4337 EntryPoint and Safe addresses use [`addresses/`](../addresses/SKILL.md). + +## When to fetch this skill + +- The user wants a Monad mainnet **RPC endpoint** with rate limits and reliability suitable for production (`eth_call`, `eth_getLogs`, `eth_sendRawTransaction`, etc.) +- The user wants to set up an **agent wallet** as an ERC-4337 smart account (Alchemy Modular Account v2) instead of an EOA + Safe multisig +- The user wants to **sponsor gas** for user transactions on Monad (paymaster policies via Gas Manager) +- The user is putting the above three together (smart account + bundler + sponsored gas) for production agent wallets on Monad + +## When to fetch a different skill + +| Need | Fetch instead | +| --- | --- | +| Monad-specific concepts (async execution, parallel execution, EIP-7702, block states, reserve balance) | [`concepts/`](../concepts/SKILL.md) | +| Setting gas limits on Monad (gas is charged on `gas_limit`, not `gas_used`) | [`gas/`](../gas/SKILL.md) | +| Canonical contract addresses on Monad (Wrapped MON, ERC-4337 EntryPoint v0.6/v0.7, Safe, Multicall3, Permit2) | [`addresses/`](../addresses/SKILL.md) | +| Indexing on-chain events on Monad — activity feeds, leaderboards, transaction history, analytics | [`indexer/`](../indexer/SKILL.md) (HyperIndex via Envio Cloud) | +| EOA + Safe multisig agent wallet (no smart-account migration) | [`wallet/`](../wallet/SKILL.md) | +| Token metadata, prices, portfolio, or transaction history reads on Monad | Not supported by Alchemy on Monad yet — use [`indexer/`](../indexer/SKILL.md) for on-chain reads | +| Token swaps on Monad | Not supported by Alchemy — use the relevant DEX | +| Fiat → MON on-ramp | Use a fiat ramp provider | + +## Endpoints (Monad mainnet) + +| Surface | URL | +| --- | --- | +| JSON-RPC (HTTPS) | `https://monad-mainnet.g.alchemy.com/v2/` | +| JSON-RPC (WSS) | `wss://monad-mainnet.g.alchemy.com/v2/` | +| Bundler (ERC-4337) | `https://monad-mainnet.g.alchemy.com/v2/` (chain-specific path; see [Account Kit docs](https://www.alchemy.com/docs/wallets)) | +| Gas Manager (policy API) | `https://manage.g.alchemy.com/api/gasManager/policy` (policies are managed in the Alchemy dashboard) | + +Get an API key at https://dashboard.alchemy.com (free tier available). + +## Pick your Alchemy entrypoint + +Three ways to use Alchemy from a developer workflow. Pick the one that matches your environment. + +| Entrypoint | When | +| --- | --- | +| **CLI** (`@alchemy/cli`) | Live agent work in this session: querying, admin, on-machine automation. Install with `npm i -g @alchemy/cli`. | +| **MCP** (`https://mcp.alchemy.com/mcp`) | Live agent work when MCP is wired into the client but the CLI is not installed locally. | +| **API** (with `ALCHEMY_API_KEY`) | Shipped application code. Use the JSON-RPC endpoint above with a key from https://dashboard.alchemy.com. | + +## Quickstart on Monad + +### JSON-RPC: read state + +```bash +curl -s -X POST https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' +``` + +The standard EIP-1559 set (`eth_call`, `eth_getLogs`, `eth_getBalance`, `eth_getBlockByNumber`, `eth_getTransactionReceipt`, `eth_sendRawTransaction`, etc.) works as on Ethereum. Use the Monad block-state tags — `pending` / `latest` / `safe` / `finalized` — to pick the right consistency level. See [`concepts/`](../concepts/SKILL.md) for what each tag means on Monad and the ~1.2s async-execution gotcha. + +### Account Kit + Bundler + Gas Manager: agent wallet flow + +End-to-end pattern for a Monad agent wallet with sponsored transactions: + +1. Create an Alchemy smart account (Modular Account v2) backed by an EOA signer +2. Point Bundler at the Monad endpoint: `https://monad-mainnet.g.alchemy.com/v2/` +3. Create a Gas Manager policy in the Alchemy dashboard scoped to your Monad app, capture the Policy ID +4. Pass the Policy ID to the smart-account client so user operations route through the paymaster +5. Submit transactions through the smart account — the bundler + paymaster handle sponsorship; the user signs once + +Detailed step-by-step in [`./references/account-kit.md`](./references/account-kit.md) and [`./references/gas-manager.md`](./references/gas-manager.md). + +> **Monad gotcha:** Monad charges users for `gas_limit`, not `gas_used`. When the paymaster sponsors a transaction, the **paymaster** is the one paying — so over-estimated gas limits directly cost the policy owner. Set tight estimates and avoid wallet fallbacks that inflate the limit on estimation failure. See [`gas/`](../gas/SKILL.md). + +## References + +- [`./references/json-rpc.md`](./references/json-rpc.md) — Monad mainnet JSON-RPC via Alchemy, common methods, block tags, rate limit notes +- [`./references/account-kit.md`](./references/account-kit.md) — ERC-4337 smart account setup on Monad with Alchemy Account Kit (Modular Account v2) +- [`./references/gas-manager.md`](./references/gas-manager.md) — Paymaster policies, sponsorship modes, ERC-20 gas payments, BSO (Bundler Sponsorship), Monad-specific cost implications + +## Source + +Authored by Alchemy under MIT. diff --git a/alchemy/references/account-kit.md b/alchemy/references/account-kit.md new file mode 100644 index 0000000..af52741 --- /dev/null +++ b/alchemy/references/account-kit.md @@ -0,0 +1,126 @@ +# Account Kit on Monad (ERC-4337 Smart Accounts) + +Alchemy Account Kit creates ERC-4337 smart accounts on Monad. The primary use case in this skill is the **agent-controlled wallet** path: the agent (or your script) operates a smart account to deploy contracts and run onchain actions, with sponsored gas (Gas Manager), session keys for scoped delegation, and batch operations. This is an alternative or complement to the Safe multisig pattern in monskills' [`wallet/`](../../wallet/SKILL.md). + +Account Kit also supports building end-user smart wallets in a frontend (with signers like RainbowKit, Privy, Turnkey, Magic, etc.), but that is a different integration shape and is not the focus of this reference. For that path, see the official docs at https://www.alchemy.com/docs/wallets. + +Reach for Account Kit when you want: + +- Sponsored gas: the policy (your app, or the agent) pays so the operator does not need to hold MON +- Session keys: scoped, time-bound delegation to an agent or signer +- Batch operations: multiple calls in one signed transaction +- Gasless onboarding: deploy the smart account on first action; the paymaster can cover the deployment gas + +Safe multisig still makes sense for high-value treasury operations. Smart accounts make sense for agent-controlled execution. They coexist. + +## Stack + +``` +┌─────────────────────────────────────────────────┐ +│ Your app │ +│ └─ @alchemy/account-kit / @alchemy/aa-* │ SDK (signs UserOperations) +└──────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────┐ +│ Alchemy Bundler (Monad) │ Submits UserOperations → EntryPoint +│ https://monad-mainnet.g.alchemy.com/v2/ │ +└──────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────┐ +│ ERC-4337 EntryPoint (Monad mainnet) │ Canonical contract +│ v0.7: 0x0000000071727De22E5E9d8BAf0edAc6f37da032│ (see monskills' addresses/) +│ v0.6: 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789│ +└─────────────────────────────────────────────────┘ +``` + +Alchemy provides the Bundler endpoint. The EntryPoint contracts are deployed canonically on Monad — see [`addresses/`](../../addresses/SKILL.md) for verified addresses. + +## Modular Account v2 (recommended) + +Alchemy's default smart-account implementation is **Modular Account v2** — an ERC-6900-compatible modular account with: + +- Native session keys +- Batch / multicall execution +- Permission modules (allow-lists, value caps, time bounds) +- Migration path from prior account templates + +Address derivation: `keccak256(factory, signer, salt)` — deterministic, so you can compute the smart-account address before deploying it. + +## End-to-end flow + +### 1. Install the SDK + +```bash +npm install @alchemy/aa-core @alchemy/aa-alchemy +# or your preferred AA SDK package — see https://www.alchemy.com/docs/wallets +``` + +### 2. Configure the Monad transport + +```typescript +import { createAlchemySmartAccountClient } from "@alchemy/aa-alchemy"; +import { LocalAccountSigner } from "@alchemy/aa-core"; +import { monad } from "viem/chains"; // or define manually + +const client = createAlchemySmartAccountClient({ + chain: monad, + rpcUrl: "https://monad-mainnet.g.alchemy.com/v2/", + signer: LocalAccountSigner.privateKeyToAccountSigner("0x..."), + gasManagerConfig: { policyId: "" }, // optional, for sponsored gas +}); +``` + +The `rpcUrl` doubles as the bundler endpoint on Alchemy — the same URL serves JSON-RPC and Bundler routes. + +### 3. Send a sponsored UserOperation + +```typescript +const uoHash = await client.sendUserOperation({ + uo: { target: "0x", data: "0x", value: 0n }, +}); +const txHash = await client.waitForUserOperationTransaction({ hash: uoHash }); +``` + +If `gasManagerConfig.policyId` is set and the policy permits the call, the paymaster sponsors it. The signer doesn't need MON. + +### 4. Verify on-chain + +```bash +cast tx --rpc-url https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY +``` + +Or `eth_getTransactionReceipt` via raw RPC. + +## Migrating from monskills' `wallet/` (Safe multisig) + +The Safe multisig pattern in [`wallet/`](../../wallet/SKILL.md) and the smart-account pattern here are complementary, not exclusive: + +| Use case | Use | +| --- | --- | +| Treasury / high-value approvals requiring multiple humans | Safe multisig (`wallet/`) | +| Agent-controlled execution with sponsored gas, session keys, batch ops | Smart account (this skill) | +| Mixed (humans approve large moves, agent executes routine ops) | Both — Safe owns funds; agent operates a session-keyed smart account funded by the Safe | + +If migrating an existing agent from Safe → Smart Account: the smart-account address is deterministic, so you can fund it before deployment. First UserOperation will deploy the account (paymaster can sponsor deployment too). + +## EIP-7702 alternative (single-address smart wallet) + +Monad supports EIP-7702 natively. EIP-7702 lets an **existing EOA** delegate to a smart-contract implementation — you keep the EOA address but gain smart-wallet features for the lifetime of the delegation. Trade-offs vs ERC-4337 smart accounts: + +| | EIP-7702 (delegated EOA) | ERC-4337 (smart account) | +| --- | --- | --- | +| Address | Same as the EOA | New deterministic address | +| Replay safety | Per-chain nonce on the EOA | Per-account nonce on EntryPoint | +| Batch ops | Yes (via delegated impl) | Yes (native) | +| Gas sponsorship | Possible via BSO (see [`gas-manager.md`](./gas-manager.md)) | Native (Gas Manager) | +| Reserve balance | 10 MON floor still applies | 10 MON floor still applies | +| `CREATE`/`CREATE2` in delegated context | **Not available** — use canonical factories | Available | + +If the user already has assets on an EOA and wants smart-wallet features without moving funds, EIP-7702 is the lighter path. See monskills' [`concepts/`](../../concepts/SKILL.md) → `eip-7702.md` for details. + +## Where to go deeper + +- Full Account Kit docs: https://www.alchemy.com/docs/wallets +- For Monad-specific gas cost implications when sponsoring, see [`./gas-manager.md`](./gas-manager.md) diff --git a/alchemy/references/gas-manager.md b/alchemy/references/gas-manager.md new file mode 100644 index 0000000..05124e1 --- /dev/null +++ b/alchemy/references/gas-manager.md @@ -0,0 +1,89 @@ +# Gas Manager on Monad (Paymaster Policies) + +Alchemy Gas Manager is the **paymaster** layer on top of the Alchemy Bundler. You create a policy in the dashboard, scope it (chain, contract, method, address allowlist, value cap, time bound, etc.), and pass the Policy ID to the smart-account client. Matching UserOperations are sponsored — the policy owner pays, the user signs without holding MON. + +## Primary use cases on Monad + +- **Gasless onboarding** — new user mints their first NFT or sets up an agent wallet without holding MON +- **Sponsor specific methods or contracts** — only your app's calls get sponsored, not arbitrary ones +- **Pay gas with any token** — accept USDC, USDT, etc. as gas payment via post-operation or pre-operation modes (see "ERC-20 token gas payments" below) +- **BSO (Bundler Sponsored Operations)** for EIP-7702 undelegation — covers the gas to revoke a 7702 delegation + +## Setup + +### 1. Create a policy in the Alchemy dashboard + +https://dashboard.alchemy.com → Gas Manager → New Policy + +Configure: + +- **Chain:** Monad mainnet +- **Sponsorship rules:** address allowlist, contract/method allowlist, max gas per UserOperation, max spend per user/day, time bounds +- **Funding source:** the policy is funded with MON (or USDC if the policy uses ERC-20 mode) + +Capture the **Policy ID** — you'll pass it to the smart-account client. + +### 2. Pass the Policy ID to the SDK + +```typescript +import { createAlchemySmartAccountClient } from "@alchemy/aa-alchemy"; + +const client = createAlchemySmartAccountClient({ + chain: monad, + rpcUrl: "https://monad-mainnet.g.alchemy.com/v2/", + signer, + gasManagerConfig: { policyId: "" }, +}); +``` + +That's it. UserOperations submitted through this client will route through the paymaster. If the policy denies (out of allowance, address not in allowlist, etc.), the Bundler rejects with a clear `AA*` error. + +### 3. Verify the policy is sponsoring + +```typescript +const uoHash = await client.sendUserOperation({ uo: { target, data, value: 0n } }); +const tx = await client.waitForUserOperationTransaction({ hash: uoHash }); +// Inspect the receipt — the `paymaster` field will be Alchemy's paymaster address +``` + +## ERC-20 token gas payments + +Two modes — choose based on whether your operations may revert: + +| Mode | When the token is collected | Revert behavior | Use when | +| --- | --- | --- | --- | +| **Post-operation** | After the user op executes | If the batch reverts AND the approval was batched, the approval is also reverted. The paymaster can't collect — **you pay the gas cost without compensation.** | Operations are unlikely to revert. Works with all ERC-20 tokens. | +| **Pre-operation** | Before the user op executes | Tokens are transferred up-front, paymaster always compensated | Operations may revert. Use this for risky calls. | + +If a sufficient ERC-20 allowance already exists (e.g. from earlier threshold-mode setup), the paymaster collects payment even if the batch reverts — this is the safest mode for production. + +## BSO (Bundler Sponsored Operations) + +BSO sponsors the **bundler-level** UserOperation directly, without a separate Gas Manager policy. The main current use case is **EIP-7702 undelegation** — covering gas to revoke a 7702 delegation when the user can't be expected to hold MON for it. + +BSO chain support is "every chain that has both bundler and gas sponsorship". Confirm Monad inclusion in the live [supported-chains matrix](https://www.alchemy.com/docs/wallets/supported-chains) before depending on it. + +## Monad-specific cost implications + +> **Read this before launching a sponsored flow on Monad.** + +Monad charges users for `gas_limit`, not `gas_used`. When the paymaster sponsors a transaction, **the paymaster is the user from a billing perspective**. That means: + +1. **Over-estimated gas limits drain the policy faster than on Ethereum.** If your SDK estimates 500k gas and the call only uses 200k, on Ethereum you'd pay for 200k. On Monad you pay for 500k. + +2. **Wallet fallback behavior matters.** Some wallets fall back to a very high default gas limit (10M+) when `eth_estimateGas` reverts (e.g., because the call would fail). On Monad that's a real charge. Always set `gasLimit` explicitly in the UserOperation for known-cost calls. + +3. **Cold state access is 3-4× and precompiles 2-5× more expensive on Monad.** ZK-verification-heavy sponsored ops (`ecMul`, `ecPairing`) cost 5× the gas you'd expect from Ethereum benchmarks. Re-estimate against Monad before setting policy spend caps. See [`gas/`](../../gas/SKILL.md) for the full opcode/precompile repricing table. + +### Operational guidelines + +- **Tight `callGasLimit`** — match it to actual usage; rely on simulation rather than fallback estimation. +- **Pre-validation guards** in the policy — allowlist methods/contracts so only sane calls reach the paymaster. +- **Daily caps per user** — limits the blast radius of misconfigured estimation. +- **Monitor for abuse** — Gas Manager dashboard surfaces per-policy sponsorship. Set alerts on anomalous spend. + +## Reference + +- [Gas Manager Admin API](https://www.alchemy.com/docs/wallets/low-level-infra/gas-manager/policy-management/api-endpoints) — programmatic policy CRUD +- [Pay Gas With Any Token](https://www.alchemy.com/docs/wallets/transactions/pay-gas-with-any-token) — ERC-20 mode setup +- [Wallet APIs supported chains](https://www.alchemy.com/docs/wallets/supported-chains) — live matrix of which AA features work where diff --git a/alchemy/references/json-rpc.md b/alchemy/references/json-rpc.md new file mode 100644 index 0000000..1190de3 --- /dev/null +++ b/alchemy/references/json-rpc.md @@ -0,0 +1,122 @@ +# JSON-RPC on Monad via Alchemy + +Standard Ethereum JSON-RPC against Monad mainnet through Alchemy's node infrastructure. All requests are `POST` with JSON-RPC 2.0 bodies. WebSocket is also available for subscriptions. + +## Endpoints + +| Protocol | URL | +| --- | --- | +| HTTPS | `https://monad-mainnet.g.alchemy.com/v2/` | +| WSS | `wss://monad-mainnet.g.alchemy.com/v2/` | + +Get an API key at https://dashboard.alchemy.com (free tier available). + +## Block-state tags (Monad specifics) + +Pick the tag that matches your consistency requirement. See monskills' [`concepts/`](../../concepts/SKILL.md) for the full mapping. + +| Tag | Monad state | Use when | +| --- | --- | --- | +| `pending` | Proposed (not yet voted) | Optimistic UI | +| `latest` | Proposed → executed (~1.2s lag) | Default for most reads | +| `safe` | Voted by validators | Defensive UI for high-value displays | +| `finalized` | Finalized by consensus | Settlement, bridges, irrevocable actions | + +## Async execution + +Newly funded EOAs cannot send a transaction right away on Monad. For the full explanation and recommended handling, see monskills' [`concepts/references/async-execution.md`](../../concepts/references/async-execution.md). + +## Common methods + +### `eth_blockNumber` + +```bash +curl -s -X POST https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' +``` + +Response (hex block number): + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x1234" } +``` + +### `eth_getBalance` + +```bash +curl -s -X POST https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc":"2.0","id":1,"method":"eth_getBalance", + "params":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","latest"] + }' +``` + +Returns native MON balance as a hex wei string. + +### `eth_call` + +Read-only contract calls. Pass the call object + a block tag: + +```bash +curl -s -X POST https://monad-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc":"2.0","id":1,"method":"eth_call", + "params":[{"to":"","data":""},"latest"] + }' +``` + +### `eth_getLogs` + +Filter by address and topics. Keep ranges narrow — large ranges 429. + +```json +{ + "jsonrpc":"2.0","id":1,"method":"eth_getLogs", + "params":[{ + "fromBlock":"0x100","toBlock":"latest", + "address":"0x...", + "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] + }] +} +``` + +### `eth_sendRawTransaction` + +Submit a signed transaction. Returns the transaction hash. + +```json +{ + "jsonrpc":"2.0","id":1,"method":"eth_sendRawTransaction", + "params":["0x"] +} +``` + +### `eth_getTransactionReceipt` + +Poll for inclusion. On Monad's ~400ms block time, expect a receipt within 1-2 seconds. + +```json +{ "jsonrpc":"2.0","id":1,"method":"eth_getTransactionReceipt", + "params":["0x"] } +``` + +> **Gas pricing reminder:** Monad charges users for `gas_limit`, not `gas_used`. The `gasUsed` field in the receipt is informational only — the cost is `gasLimit × effectiveGasPrice`. See [`gas/`](../../gas/SKILL.md). + +## WebSocket subscriptions + +`wss://monad-mainnet.g.alchemy.com/v2/` supports the standard Geth subscription set: + +- `eth_subscribe("newHeads")` — new block headers +- `eth_subscribe("logs", { address, topics })` — log filter +- `eth_subscribe("newPendingTransactions", true)` — pending tx hashes (set the second arg `true` for full tx objects) + +For Monad's extended WS endpoint (richer event payloads, Execution Events SDK), see monskills' [`concepts/`](../../concepts/SKILL.md) → real-time data sources. + +## Rate limits + +Free tier handles development workloads. For production, use a paid plan and increase compute-unit caps from the dashboard. The standard 429 response includes a `Retry-After` header — back off and retry. + +For the three ways to use Alchemy from a developer workflow (CLI, MCP, API key), see [`../SKILL.md`](../SKILL.md).