{"id":22197886,"url":"https://github.com/onmax/albatross-rpc-client-ts","last_synced_at":"2025-07-27T01:31:37.775Z","repository":{"id":142750652,"uuid":"614086103","full_name":"onmax/albatross-rpc-client-ts","owner":"onmax","description":"A fully typed Nimiq RPC client for TypeScript.","archived":false,"fork":false,"pushed_at":"2024-11-27T21:10:28.000Z","size":806,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-30T14:41:49.707Z","etag":null,"topics":["albatross","nimiq","rpc-client"],"latest_commit_sha":null,"homepage":"https://nimiq.github.io/nimiq-developer-center/build/rpc-docs/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onmax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-14T21:32:15.000Z","updated_at":"2024-11-27T21:10:30.000Z","dependencies_parsed_at":"2024-09-06T13:39:45.232Z","dependency_job_id":"006e756c-2358-4d83-90c0-7c1dcc6e6cd2","html_url":"https://github.com/onmax/albatross-rpc-client-ts","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Falbatross-rpc-client-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Falbatross-rpc-client-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Falbatross-rpc-client-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Falbatross-rpc-client-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onmax","download_url":"https://codeload.github.com/onmax/albatross-rpc-client-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227741657,"owners_count":17812894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["albatross","nimiq","rpc-client"],"created_at":"2024-12-02T14:24:30.530Z","updated_at":"2025-07-27T01:31:37.768Z","avatar_url":"https://github.com/onmax.png","language":"TypeScript","funding_links":[],"categories":["Developer Resources"],"sub_categories":["RPC"],"readme":"# Nimiq Albatross RPC Client for TypeScript\n\nA fully typed Nimiq Albatross RPC client for TypeScript with support for both HTTP and WebSocket connections.\n\n## Installation\n\n```bash\n# Using npm\nnpm install nimiq-rpc-client-ts\n\n# Using yarn\nyarn add nimiq-rpc-client-ts\n\n# Using pnpm\npnpm add nimiq-rpc-client-ts\n```\n\n## Configuration\n\nThe client can be configured in multiple ways:\n\n### 1. Using `initRpcClient` (recommended)\n\n```typescript\nimport { initRpcClient } from 'nimiq-rpc-client-ts'\n\n// Initialize with URL only\ninitRpcClient({\n  url: 'https://rpc.nimiq-testnet.com'\n})\n\n// Initialize with URL and authentication\ninitRpcClient({\n  url: 'https://rpc.nimiq-testnet.com',\n  auth: {\n    username: 'your-username',\n    password: 'your-password'\n  }\n})\n```\n\n### 2. Using environment variables\n\n```bash\n# Set these environment variables before running your application\nexport ALBATROSS_RPC_NODE_URL=https://rpc.nimiq-testnet.com\nexport ALBATROSS_RPC_NODE_USERNAME=your-username\nexport ALBATROSS_RPC_NODE_PASSWORD=your-password\n```\n\n### 3. Per-request configuration\n\nYou can also override configuration on a per-request basis:\n\n```typescript\nimport { getBlockNumber } from 'nimiq-rpc-client-ts'\n\n// Override URL and auth for a specific request\nconst result = await getBlockNumber({\n  url: new URL('https://rpc.nimiq-testnet.com'),\n  auth: {\n    username: 'your-username',\n    password: 'your-password'\n  }\n})\n```\n\n## Module Resolution Setup\n\nThis library is published as an ESM-only package with subpath exports. To use it properly, make sure your TypeScript project is configured for ESM:\n\n```json\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\", // or higher\n    \"module\": \"NodeNext\", // or \"ESNext\" with \"moduleResolution\": \"Bundler\"\n    \"moduleResolution\": \"NodeNext\", // or \"Bundler\" if using \"module\": \"ESNext\"\n    \"esModuleInterop\": true\n    // Other compiler options...\n  }\n}\n```\n\nImport from specific subpaths like this:\n\n```typescript\n// Import types\nimport type { Account, Block } from 'nimiq-rpc-client-ts/types'\n\n// Import configuration utilities\nimport { initRpcClient } from 'nimiq-rpc-client-ts/config'\n\n// Import HTTP methods\nimport { getAccountByAddress, getBlockNumber } from 'nimiq-rpc-client-ts/http'\n\n// Import WebSocket methods\nimport { subscribeForHeadBlock } from 'nimiq-rpc-client-ts/ws'\n```\n\n## HTTP API Usage\n\nAll HTTP RPC methods are exposed as individual functions.\n\nThe methods have either one or two parameters:\n\n- If the RPC method does not have any parameters, then the first parameter is an options object for the request.\n- If the RPC method has parameters, then the first parameter is the method-specific parameters and the second parameter is an options object.\n\n```typescript\nimport {\n  getAccountByAddress,\n  getBlockByHash,\n  getBlockNumber,\n  sendTransaction\n} from 'nimiq-rpc-client-ts'\n\n// Simple call without options\nconst [success, error, result, meta] = await getBlockNumber()\nif (success \u0026\u0026 result) {\n  console.log(`Current block number: ${result}`)\n}\n\n// Call with options\nconst [success, error, block, meta] = await getBlockByHash({ /* Params first */\n  hash: 'abcd1234...', // Block hash\n  includeBody: true // Method-specific option\n})\n\n// Working with accounts\nconst [success, error, account, meta] = await getAccountByAddress('NQ...')\n\n// Sending transactions\nconst [success, error, txHash, meta] = await sendTransaction({\n  wallet: 'NQ...',\n  recipient: 'NQ...',\n  value: 1000,\n  fee: 10,\n  relativeValidityStartHeight: 0 // or use absoluteValidityStartHeight\n})\n\n// All results are returned as tuples: [success, error, data, metadata]\n// - success: boolean indicating if the call was successful\n// - error: error message if the call failed\n// - data: the actual result data if successful\n// - metadata: additional information about the request\n```\n\n## WebSocket Subscriptions\n\nSubscribe to real-time events using the WebSocket API:\n\n```typescript\nimport {\n  LogType,\n  subscribeForHeadBlock,\n  subscribeForHeadBlockHash,\n  subscribeForLogsByAddressesAndTypes\n} from 'nimiq-rpc-client-ts'\n\n// Subscribe to new blocks\nconst blockSubscription = await subscribeForHeadBlock(true, {\n  // Optional settings\n  once: false, // Set to true to auto-unsubscribe after first message\n  filter: block =\u003e block.number \u003e 100, // Filter events\n  timeout: 30000, // Timeout in ms (default: 30000, false to disable)\n  autoReconnect: true, // Auto reconnect on disconnect\n  onError: e =\u003e console.error(e)\n})\n\n// Listen for block events\nblockSubscription.addEventListener('data', (event) =\u003e {\n  const { data: block, metadata } = event.detail\n  console.log('New block:', block.number, block.hash)\n})\n\n// Subscribe to head block hashes only (lighter)\nconst hashSubscription = await subscribeForHeadBlockHash()\nhashSubscription.addEventListener('data', (event) =\u003e {\n  const { data: hashes } = event.detail\n  console.log('New block hashes:', hashes)\n})\n\n// Subscribe to specific log types for addresses\nconst logSubscription = await subscribeForLogsByAddressesAndTypes(\n  ['NQ...', 'NQ...'], // Addresses to monitor\n  [LogType.Transfer, LogType.PayFee] // Log types to monitor\n)\n\n// Handle connection events\nblockSubscription.addEventListener('open', () =\u003e console.log('Connected'))\nblockSubscription.addEventListener('error', event =\u003e console.error('Error:', event.detail))\nblockSubscription.addEventListener('close', () =\u003e console.log('Disconnected'))\n```\n\n## Migration Guide from v0.0.0 to v1.0.0\n\nIf you're migrating from v0.0.0 to v1.0.0, here are the key changes:\n\n### Class-based to Functional API\n\n**Before (v0.0.0):**\n\n```typescript\nimport { NimiqRPCClient } from 'nimiq-rpc-client-ts'\n\nconst client = new NimiqRPCClient(new URL('NODE_URL'))\nconst { data: currentEpoch, error } = await client.blockchain.getEpochNumber()\n```\n\n**After (v1.0.0):**\n\n```typescript\nimport { getEpochNumber, initRpcClient } from 'nimiq-rpc-client-ts'\n\n// Initialize once at app startup\ninitRpcClient({ url: 'NODE_URL' })\n\n// Make calls using direct functions\nconst [success, error, currentEpoch, metadata] = await getEpochNumber()\n```\n\n### Return Value Format\n\n**Before (v0.0.0):**\n\n```typescript\nconst { data, error } = await client.blockchain.getBlockNumber()\nif (error || !data) {\n  console.error('Error:', error)\n}\nelse {\n  console.log('Block number:', data)\n}\n```\n\n**After (v1.0.0):**\n\n```typescript\nconst [success, error, blockNumber, metadata] = await getBlockNumber()\nif (!success || !blockNumber) {\n  console.error('Error:', error)\n}\nelse {\n  console.log('Block number:', blockNumber)\n}\n```\n\n### WebSocket Subscriptions\n\n**Before (v0.0.0):**\n\n```typescript\nconst { next } = await client.subscribe.forHeadBlock()\nnext(block =\u003e console.log(block))\n```\n\n**After (v1.0.0):**\n\n```typescript\nconst subscription = await subscribeForHeadBlock()\nsubscription.addEventListener('data', (event) =\u003e {\n  const { data: block } = event.detail\n  console.log(block)\n})\n```\n\n## Custom RPC Methods\n\nIf you need to call custom methods not covered by the library:\n\n```typescript\nimport { rpcCall, rpcSubscribe } from 'nimiq-rpc-client-ts'\n\n// For HTTP RPC\nconst [success, error, data, meta] = await rpcCall\u003cYourResponseType\u003e(\n  'yourCustomMethod',\n  ['param1', 'param2'],\n  { /* options */ }\n)\n\nconst subscription = await rpcSubscribe\u003cYourEventType\u003e(\n  'subscribeToYourCustomEvents',\n  ['param1', 'param2'],\n  { /* options */ }\n)\n```\n\n## Type Augmentation\n\nYou can extend the library's types for custom needs:\n\n```typescript\n// albatross-rpc-client-ts.d.ts\ndeclare module 'nimiq-rpc-client-ts' {\n  interface Block {\n    myCustomProperty: string\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Falbatross-rpc-client-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonmax%2Falbatross-rpc-client-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Falbatross-rpc-client-ts/lists"}