{"id":22380215,"url":"https://github.com/jangolle/monobank-api-client","last_synced_at":"2025-09-21T22:31:02.625Z","repository":{"id":41117516,"uuid":"194280409","full_name":"jangolle/monobank-api-client","owner":"jangolle","description":"Monobank API client wrapper build on promises","archived":false,"fork":false,"pushed_at":"2024-07-11T08:12:40.000Z","size":258,"stargazers_count":43,"open_issues_count":10,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-30T22:48:26.195Z","etag":null,"topics":["monobank","monobank-api","monobank-client","monobank-node"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jangolle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2019-06-28T13:42:38.000Z","updated_at":"2024-10-16T19:35:20.000Z","dependencies_parsed_at":"2024-12-04T23:13:26.667Z","dependency_job_id":"3dcabfb4-2254-4018-9704-1164ba353452","html_url":"https://github.com/jangolle/monobank-api-client","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":0.1333333333333333,"last_synced_commit":"17de7d1f4d5c1b67daf4b4390c10ac3a81d646b8"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangolle%2Fmonobank-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangolle%2Fmonobank-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangolle%2Fmonobank-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jangolle%2Fmonobank-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jangolle","download_url":"https://codeload.github.com/jangolle/monobank-api-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233802427,"owners_count":18732535,"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":["monobank","monobank-api","monobank-client","monobank-node"],"created_at":"2024-12-04T23:13:23.503Z","updated_at":"2025-09-21T22:30:57.381Z","avatar_url":"https://github.com/jangolle.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![node](https://img.shields.io/node/v/monobank-api-client.svg?style=flat-square)\n![npm](https://img.shields.io/npm/v/monobank-api-client.svg?style=flat-square)\n![npm](https://img.shields.io/npm/dm/monobank-api-client.svg?style=flat-square)\n![Travis (.org)](https://img.shields.io/travis/JanGolle/monobank-api-client.svg?style=flat-square)\n![Codecov](https://img.shields.io/codecov/c/github/JanGolle/monobank-api-client.svg?style=flat-square)\n\n# Monobank API client for Node.JS\n\n![monocat](https://user-images.githubusercontent.com/6859896/60575987-3102f780-9d85-11e9-986e-b7126af57f8d.png)\n\nMonobank API client wrapper build on promises.\n\n## Installation\n\n### yarn:\n\n```\nyarn add monobank-api-client\n```\n\n### npm:\n\n```\nnpm i monobank-api-client\n```\n\n# Usage\n\n## Personal API\n\nRead docs here - https://api.monobank.ua/docs/\n\nVisit https://api.monobank.ua - read QR code retrieve your personal `TOKEN` here.\n\n### Create personal client instance\n\n```javascript\nconst { ClientFactory } = require('monobank-api-client');\n\nconst api = ClientFactory.createPersonal(TOKEN);\n```\n\n### Get currency list\n\n```javascript\nconst currencyInfo = await api.getCurrencyInfo();\n```\n\n`currencyInfo` is list of `CurrencyInfo` DTO.\n\n```shell\nCurrencyInfo {\n    _currencyCodeA:\n     { code: 'USD',\n       number: '840',\n       digits: 2,\n       currency: 'US Dollar',\n       countries: [Array] },\n    _currencyCodeB:\n     { code: 'UAH',\n       number: '980',\n       digits: 2,\n       currency: 'Hryvnia',\n       countries: [Array] },\n    _date: 2019-07-11T07:10:05.000Z,\n    _rateSell: 26.0988,\n    _rateBuy: 25.761,\n    _rateCross: undefined }\n```\n\n### Get statement by account ID\n\n```javascript\nconst statement = await api.getStatement({\n  account: 'ACCOUNT_ID',\n  from: new Date('2019-07-04'),\n  to: new Date('2019-07-11'),\n});\n```\n\n`statement` is list of `Transaction` DTO.\n\n```shell\nTransaction {\n    _id: 'xxxxxxxx',\n    _time: 2019-07-10T17:04:51.000Z,\n    _description: 'Uber',\n    _mcc: 4111,\n    _hold: true,\n    _amount: -800,\n    _operationAmount: -800,\n    _currencyCode:\n     { code: 'UAH',\n       number: '980',\n       digits: 2,\n       currency: 'Hryvnia',\n       countries: [Array] },\n    _commissionRate: 0,\n    _cashbackAmount: 0,\n    _balance: 81129811 }\n```\n\n### Get statement by currency code\n\n```javascript\nconst statement = await api.getStatementByCurrencyCode({\n  currencyCode: 'UAH',\n  from: new Date('2019-07-04'),\n  to: new Date('2019-07-11'),\n});\n```\n\nResponse will be the same as for previous example.\n\n## Corporate API\n\nRead docs here - https://api.monobank.ua/docs/corporate.html\n\n### Get access\n\n#### Generate private key\n\n```shell\nopenssl ecparam -genkey -name secp256k1 -rand /dev/urandom -out priv.key\n```\n\nOut file is `priv.key`\n\n**Be careful!** don't share it with anyone\n\n#### Generate public key\n\n```shell\nopenssl ec -in priv.key -pubout -out pub.key\n```\n\nOut file is `pub.key`\n\n#### Request API access\n\nSend an email to api@monobank.ua with next info:\n\n1. app name\n2. short description of your app or service\n3. attach app logo (.jpg, .png) file\n4. attach `pub.key` file **(not private!)**\n\nIf everything is OK, then you will get approve and `KEY_ID`.\n\nNow you can start using corporate API.\n\n### Create corporate client instance\n\n```javascript\nconst { ClientFactory } = require('monobank-api-client');\n\nconst api = ClientFactory.createCorporate(KEY_ID, '/path/to/priv.key');\n```\n\n### Create access request\n\n```javascript\nconst accessInfo = await api.getAccessRequest({ permissions: [Permission.GET_PERSONAL_INFO] });\n```\n\n`accessInfo` is instance of `AccessInfo` DTO:\n\n```shell\nAccessInfo {\n  _tokenRequestId: 'aL67772mA7PlJygFjzQP111',\n  _acceptUrl: 'https://mbnk.app/auth/aL67772mA7PlJygFjzQP111' }\n```\n\nStore `tokenRequestId` to DB and give user `acceptUrl` link.\n\n### Check access is granted\n\n```javascript\nconst isGranted = await api.checkAccessRequest({ requestid: 'aL67772mA7PlJygFjzQP111' });\n```\n\nOther use cases of corporate API same to personal with same interface.\n\n# Error handling\n\nMost of bad cases mapped to custom error classes. All NOT-OK responses from API also mapped to errors, so you could handle them by their classes too.\n\nActual list below.\n\n- `InvalidPrivateKeyError`;\n- `TooManyRequestsError`;\n- `InvalidPermissionValueError`;\n- `AccessForbiddenError`;\n- `InvalidRequestParamsError`;\n- `NotFoundError`;\n- `UnauthorizedRequestError`;\n- `UndefinedApiError`;\n\n# Examples\n\nCheck [examples](https://github.com/JanGolle/monobank-api-client/tree/master/examples) directory for more use cases.\n\n## Run personal API example\n\n```shell\nTOKEN='your-personal-token-here' node examples/personal-app.js\n```\n\n## Run corporate API example\n\n```shell\nKEY_ID='key-id-given-by-monobank' PRIVATE_KEY='path/to/priv.key' node examples/personal-app.js\n```\n\n**FYI:** Corporate API example has `5s` access granted check.\n\n```shell\njangolle@imac:/monobank-api-client$ KEY_ID=xxxxxxx PRIVATE_KEY=/xxxx/xxxx/priv.key node examples/corporate-app.js\nGo to 'https://mbnk.app/auth/xxxxxxxxxxxxxxxxx' from your mobile device with Monobank client and grant access.\nAccess for requestId \"xxxxxxxxxxxxxxxxx\" not granted yet. Auto-check in 5s..\nAccess for requestId \"xxxxxxxxxxxxxxxxx\" not granted yet. Auto-check in 5s..\nAccess for requestId \"xxxxxxxxxxxxxxxxx\" not granted yet. Auto-check in 5s..\nAccess granted successfully!\n\n```\n\n# FAQ\n\n### Q: Why I receive list of transactions and operation amounts and balances so big (x100) of real amount by my card?\n\n**A:** Everything is OK. Operation amounts and account balances represented as `int64` amount of currency with minor units.\n\nIf you need normalized value just do next calculation:\n\n```javascript\nconst normalizedAmount = transaction.amount / Math.pow(10, transaction.currencyCode.digits);\n```\n\n`monobank-api-client` use `currency-codes` module as dictionary for `ISO 4217` to detect minor units and country of usage for currency.\n\n# Roadmap\n\n- Tests\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjangolle%2Fmonobank-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjangolle%2Fmonobank-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjangolle%2Fmonobank-api-client/lists"}