feat: add getBalance action (#35)

* feat: add getBalance action across relayer, account, and bundler

Add gelato_getBalance RPC support to query Gas Tank balance from all
three client types. Includes tests, fixtures, examples, and README docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: changeset

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: pedrocrvz

.changeset/config.json

@@ -12,7 +12,9 @@
     "account-sponsored-payment",
     "account-ws",
     "relayer-ws",
-    "bundler-ws"
+    "bundler-ws",
+    "relayer-get-balance",
+    "bundler-get-balance"
   ],
   "linked": [],
   "updateInternalDependencies": "patch"

.changeset/wicked-sloths-count.md

@@ -0,0 +1,5 @@
+---
+"@gelatocloud/gasless": patch
+---
+
+feat: gas tank balance action

README.md

@@ -251,6 +251,15 @@ await relayer.ws.unsubscribe(subscription.subscriptionId);
 relayer.ws.disconnect();
 ```
 
+### Get Balance
+
+Check your Gas Tank balance. Available on all client types.
+
+```typescript
+const { balance, decimals, unit } = await relayer.getBalance();
+// Also: client.getBalance(), bundler.getBalance()
+```
+
 ## Sync vs Async
 
 The SDK offers two ways to send transactions:
@@ -307,6 +316,7 @@ const client = createGelatoEvmRelayerClient({
 | `sendTransactionSync` | `{ chainId, to, data, timeout?, pollingInterval?, throwOnReverted?, ... }` | `Promise<TransactionReceipt>` | Send and wait for receipt |
 | `getStatus` | `{ id: string }` | `Promise<Status>` | Get transaction status |
 | `waitForReceipt` | `{ id: string, timeout?, pollingInterval?, throwOnReverted? }` | `Promise<TransactionReceipt>` | Wait for receipt, throws on failure |
+| `getBalance` | - | `Promise<Balance>` | Get Gas Tank balance |
 | `getCapabilities` | - | `Promise<Capabilities>` | Get supported chains |
 | `getFeeData` | `{ chainId, gas, l1Fee? }` | `Promise<FeeData>` | Get network fee data |
 
@@ -344,6 +354,7 @@ const client = await createGelatoSmartAccountClient({
 | `sendTransactionSync` | `{ calls, nonce?, nonceKey?, timeout?, pollingInterval?, throwOnReverted?, ... }` | `Promise<TransactionReceipt>` | Send and wait for receipt |
 | `getStatus` | `{ id: string }` | `Promise<Status>` | Get transaction status |
 | `waitForReceipt` | `{ id: string, timeout?, pollingInterval?, throwOnReverted? }` | `Promise<TransactionReceipt>` | Wait for receipt, throws on failure |
+| `getBalance` | - | `Promise<Balance>` | Get Gas Tank balance |
 | `getCapabilities` | - | `Promise<Capabilities>` | Get supported chains |
 
 **Nonce Options:**
@@ -397,6 +408,7 @@ const bundler = await createGelatoBundlerClient({
 | `sendUserOperation` | `{ calls }` | `Promise<Hex>` | Send a user operation |
 | `sendUserOperationSync` | `{ calls, timeout?, pollingInterval? }` | `Promise<UserOperationReceipt>` | Send and wait for receipt |
 | `waitForUserOperationReceipt` | `{ hash }` | `Promise<{ receipt }>` | Wait for receipt |
+| `getBalance` | - | `Promise<Balance>` | Get Gas Tank balance |
 | `estimateUserOperationGas` | `UserOperationParams` | `Promise<GasEstimate>` | Estimate gas |
 | `prepareUserOperation` | `UserOperationParams` | `Promise<UserOperation>` | Prepare operation |
 | `getUserOperationGasPrice` | - | `Promise<GasPrice>` | Get current gas prices |
@@ -622,8 +634,10 @@ const receipt = await relayer.sendTransactionSync({
 See the [`/examples`](./examples) directory for complete working examples:
 
 - [`examples/relayer/sponsored`](./examples/relayer/sponsored) - Direct relayer usage
+- [`examples/relayer/get-balance`](./examples/relayer/get-balance) - Get Gas Tank balance
 - [`examples/account/sponsored`](./examples/account/sponsored) - Gelato smart account
 - [`examples/bundler/sponsored`](./examples/bundler/sponsored) - ERC-4337 bundler
+- [`examples/bundler/get-balance`](./examples/bundler/get-balance) - Get Gas Tank balance (bundler)
 - [`examples/relayer/ws`](./examples/relayer/ws) - Relayer WebSocket usage
 - [`examples/bundler/ws`](./examples/bundler/ws) - Bundler WebSocket usage
 - [`examples/account/ws`](./examples/account/ws) - Account WebSocket usage

examples/bundler/get-balance/.env.example

@@ -0,0 +1 @@
+GELATO_API_KEY="Get your api key at https://app.gelato.cloud/"

examples/bundler/get-balance/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "bundler-get-balance",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@gelatocloud/gasless": "workspace:*",
+    "viem": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "catalog:"
+  }
+}

examples/bundler/get-balance/src/index.ts

@@ -0,0 +1,54 @@
+import { resolve } from 'node:path';
+import { config } from 'dotenv';
+
+// Load root .env first (defaults)
+config({ path: resolve(__dirname, '../../../../.env'), quiet: true });
+
+// Load local .env to override (optional)
+config({ override: true, quiet: true });
+
+import { createGelatoBundlerClient, toGelatoSmartAccount } from '@gelatocloud/gasless';
+import { createPublicClient, type Hex, http } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { baseSepolia } from 'viem/chains';
+
+const GELATO_API_KEY = process.env['GELATO_API_KEY'];
+const PRIVATE_KEY = process.env['PRIVATE_KEY'];
+
+if (!GELATO_API_KEY) {
+  throw new Error('GELATO_API_KEY is not set');
+}
+
+const chain = baseSepolia;
+
+const main = async () => {
+  const owner = privateKeyToAccount((PRIVATE_KEY ?? generatePrivateKey()) as Hex);
+
+  const client = createPublicClient({
+    chain,
+    transport: http()
+  });
+
+  const account = toGelatoSmartAccount({
+    client,
+    owner
+  });
+
+  const bundler = await createGelatoBundlerClient({
+    account,
+    apiKey: GELATO_API_KEY,
+    client,
+    sponsored: true
+  });
+
+  const { balance, decimals, unit } = await bundler.getBalance();
+
+  console.log(`Balance: ${balance} (${decimals} decimals, ${unit})`);
+
+  process.exit(0);
+};
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

examples/bundler/get-balance/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../tsconfig.json"
+}

examples/relayer/get-balance/.env.example

@@ -0,0 +1 @@
+GELATO_API_KEY="Get your api key at https://app.gelato.cloud/"

examples/relayer/get-balance/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "relayer-get-balance",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@gelatocloud/gasless": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "catalog:"
+  }
+}

examples/relayer/get-balance/src/index.ts

@@ -0,0 +1,29 @@
+import { resolve } from 'node:path';
+import { config } from 'dotenv';
+
+// Load root .env first (defaults)
+config({ path: resolve(__dirname, '../../../../.env'), quiet: true });
+
+// Load local .env to override (optional)
+config({ override: true, quiet: true });
+
+import { createGelatoEvmRelayerClient } from '@gelatocloud/gasless';
+
+const GELATO_API_KEY = process.env['GELATO_API_KEY'];
+
+if (!GELATO_API_KEY) {
+  throw new Error('GELATO_API_KEY is not set');
+}
+
+const main = async () => {
+  const relayer = createGelatoEvmRelayerClient({ apiKey: GELATO_API_KEY });
+
+  const { balance, decimals, unit } = await relayer.getBalance();
+
+  console.log(`Balance: ${balance} (${decimals} decimals, ${unit})`);
+};
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});