{"id":42584063,"url":"https://github.com/sn0rp/finense","last_synced_at":"2026-02-28T11:10:24.911Z","repository":{"id":65184681,"uuid":"454199706","full_name":"sn0rp/finense","owner":"sn0rp","description":"RESTful API to aggregate ENS records and estimate net worth","archived":false,"fork":false,"pushed_at":"2022-05-05T20:49:57.000Z","size":509,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-01-29T10:59:09.338Z","etag":null,"topics":["api","blockchain","crypto","cryptocurrency","ens","eth","ether","ethereum","ethers","ethers-js","ethersjs","express","express-js","expressjs","node","node-js","nodejs","nodemon","npm","rest"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sn0rp.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}},"created_at":"2022-01-31T23:07:56.000Z","updated_at":"2022-05-05T20:49:16.000Z","dependencies_parsed_at":"2023-01-07T10:05:21.365Z","dependency_job_id":null,"html_url":"https://github.com/sn0rp/finense","commit_stats":null,"previous_names":["snorper/finense"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sn0rp/finense","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sn0rp%2Ffinense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sn0rp%2Ffinense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sn0rp%2Ffinense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sn0rp%2Ffinense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sn0rp","download_url":"https://codeload.github.com/sn0rp/finense/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sn0rp%2Ffinense/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29931532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T09:58:13.507Z","status":"ssl_error","status_checked_at":"2026-02-28T09:57:57.047Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["api","blockchain","crypto","cryptocurrency","ens","eth","ether","ethereum","ethers","ethers-js","ethersjs","express","express-js","expressjs","node","node-js","nodejs","nodemon","npm","rest"],"created_at":"2026-01-28T22:39:03.489Z","updated_at":"2026-02-28T11:10:24.880Z","avatar_url":"https://github.com/sn0rp.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003ci\u003eFINENSE\u003c/i\u003e\u003c/h1\u003e\r\n\u003cdiv align=\"center\"\u003e\u003cimg alt=\"finense logo\" style=\"width: 50%; height: auto\" src=\"finense_logo.png\"\u003e\u003c/div\u003e\r\n\u003cp align =\"center\"\u003e\r\n  \u003ci\u003eRESTful API to aggregate ENS records and estimate net worth\u003c/i\u003e\r\n\u003c/p\u003e\r\n\u003cdiv align=\"center\"\u003e\r\n  \u003ca href=\"https://github.com/Snorper/finense/actions\"\u003e\u003cimg alt=\"Workflow\" src=\"https://img.shields.io/github/workflow/status/Snorper/finense/Jest\"\u003e\u003c/a\u003e\r\n  \u003ca href=\"https://github.com/snorper/finense/issues\"\u003e\u003cimg alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues/snorper/finense?color=brightgreen\"\u003e\u003c/a\u003e\r\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License badge\" src=\"https://img.shields.io/github/license/snorper/finense?color=brightgreen\"\u003e\u003c/a\u003e\r\n  \u003cbr\u003e\r\n  \u003ca href=\"https://github.com/Snorper/finense/stargazers\"\u003e\u003cimg alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/snorper/finense?style=social\"\u003e\u003c/a\u003e\r\n  \u003ca href=\"https://github.com/Snorper/finense/watchers\"\u003e\u003cimg alt=\"GitHub Watchers\" src=\"https://img.shields.io/github/watchers/snorper/finense?style=social\"\u003e\u003c/a\u003e\r\n\u003c/div\u003e\r\n\r\n## Table of Contents\r\n- [About](#about)\r\n- [Setup](#setup)\r\n- [Usage](#usage)\r\n- [Dependencies](#dependencies)\r\n- [Self-Hosting](#self-hosting)\r\n- [Roadmap](#roadmap)\r\n- [License](#license)\r\n\r\n## About\r\n*Finense* is an API which simplifies the process of evaluating one's cryptocurrency portfolio for ENS domain registrants. The original goal of this software was to evaluate a domain's \"Net Worth\" in USD; this goal has been satisfied with regard to major cryptocurrency assets. This software is *not* built to allow any modification of ENS or other blockchain data and only `GET` requests are supported. Functionality is delivered in the form of a self-hosted API. I do intend to utilize the lessons learned here within a more robust portfolio analysis application in the distant future, however I make no public commitment at this time.\r\n\r\nThis software was created to meet a personal need, although the utility is self-evident.\r\n\r\n## Setup\r\nThese directions assume the user will deploy on a Debian server with Docker. If you just want to run the software with Node, you can simply clone this repository, create the required environment variables (Step 4), and run `npm run start`. If you already have Docker and Screen installed, skip to Step 4.\r\n\r\n1. Deploy a new Debian server, if applicable.\r\n2. Uninstall outdated versions of Docker (this step taken from Docker documentation)\r\n```bash\r\napt remove docker docker-engine docker.io containerd runc\r\n```\r\n3. Install Docker, Git, Screen (this step taken from Docker documentation)\r\n```bash\r\napt update\r\n\r\napt install ca-certificates curl gnupg lsb-release\r\n\r\ncurl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg\r\n\r\necho \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable\" | tee /etc/apt/sources.list.d/docker.list \u003e /dev/null\r\n\r\napt install docker-ce docker-ce-cli containerd.io docker-compose-plugin screen git\r\n```\r\n4. Download and configure Finense\r\n```bash\r\ngit clone https://github.com/snorper/finense\r\n\r\ncd finense\r\n\r\ncat \u003e\u003e ./.env\u003c\u003c EOF\r\nINFURA_ID=     ***FILL THIS IN***\r\nINFURA_SECRET= ***FILL THIS IN***\r\nNOW_NODES=     ***FILL THIS IN***\r\nPORT=5000\r\nNODE_ENV=\"production\"\r\nEOF\r\n```\r\nRegarding the above environment variables:\r\n- INFURA_ID is your *Infura Project ID*.\r\n- INFURA_SECRET is your *Infura Project Secret*.\r\n- NOW_NODES is your *NOWNodes API Key*.\r\n- PORT is the port on which the API will listen (default 5000).\r\n\r\nUndisclosed environment variables are to be supplied by the user in a local deployment. Replace `***FILL THIS IN***` with the relevant information, in quotes with no spaces.\r\n\r\n5. Run Finense\r\n```bash\r\nscreen -S finense\r\n\r\ndocker compose up\r\n```\r\n- To exit and leave finense running, press `CTRL+A` and then `D`.\r\n- To return after exiting, run `screen -r finense`.\r\n- To stop finense, run `screen -X -S finense quit`.\r\n\r\n## Usage\r\nIf you followed the suggested steps from Setup, the API is now accessible at [localhost:5000](http://localhost:5000). All endpoints and errors are fully documented at `docs/index.md` in this repository, linked [here](https://github.com/Snorper/finense/blob/master/docs/index.md). As an example, sending a `GET` request or otherwise navigating to [http://localhost:5000/domain/snorp.eth](http://localhost:5000/domain/snorp.eth) returns the following response:\r\n```json\r\n{\r\n    \"domain\": \"snorp.eth\",\r\n    \"avatar\": \"https://gateway.ipfs.io/ipfs/Qmbkc7q1MASig2BpizCXwR4tUUq4GG7ubQ15VucAf1B5pq/493.png\",\r\n    \"net\": \"4726.272173353719\",\r\n    \"assets\": [\r\n        {\r\n            \"name\": \"eth\",\r\n            \"address\": \"0x0FA6273Ce887D26622698eAbc9311597fC66a351\",\r\n            \"balance\": \"0.8440922705248084\",\r\n            \"usd\": \"2338.1355893537193\"\r\n        },\r\n        {\r\n            \"name\": \"btc\",\r\n            \"address\": \"bc1q9x8660cp73x2v3lyvm6ua9gqwz6fy8gqhrsv06\",\r\n            \"balance\": \"0.06419722\",\r\n            \"usd\": \"2388.136584\"\r\n        },\r\n        {\r\n            \"name\": \"ltc\",\r\n            \"address\": \"ltc1qlf0s82v7ywvnf52c0jk9ejx6qfsragk58pgvmp\",\r\n            \"balance\": \"0\",\r\n            \"usd\": \"0\"\r\n        },\r\n        {\r\n            \"name\": \"doge\",\r\n            \"address\": \"D6LVbmQM3UQmvwFnWX8VKECJH7ySNnYzX9\",\r\n            \"balance\": \"0\",\r\n            \"usd\": \"0\"\r\n        }\r\n    ]\r\n}\r\n```\r\nInformational messages and errors are logged to `finense.log` in the project root directory. If you make regular use of this software, you may want to occasionally delete that file using `cron` or a similar tool.\r\n\r\nNote that this API supports four assets: btc, ltc, eth, and doge. Support for additional assets would require additional upstream API dependencies, which explains why it is common to support just these four. I do not intend to integrate any additional APIs, but feedback is welcome.\r\n\r\n## Dependencies\r\nProper functionality is dependent upon other upstream APIs remaining accessible. If at any time these APIs cannot be reached, *Finense* is expected to return an \"UpstreamError\" with status code 502. Beyond this, all routes and underlying functions are tested. Errors should only be returned if the user supplies a dissallowed or misspelled request.\r\n\r\n## Roadmap\r\n- [X] Determine best approach in detail\r\n- [X] Create `README.md` skeleton\r\n- [X] Communicate with ENS and relevant blockchain APIs to get necessary data\r\n    - [X] Connect to Ethereum \u0026 establish resolver for arbitrary domains\r\n    - [X] Resolve domain to list of coin types with address records\r\n    - [X] Filter a domain's coin types list for supported assets\r\n    - [X] Resolve each supported coin type to the given domain's matching address record\r\n    - [X] Get amount owned for each supported asset\r\n    - [X] Convert amounts owned to USD\r\n    - [X] Aggregate amounts owned for all supported assets to calculate net worth\r\n- [X] API Development\r\n    - [X] Create API skeleton\r\n    - [X] Fill in API routes using ENS scripts\r\n        - [X] `/:domain`: provide net worth and asset breakdown\r\n        - [X] `/:domain/address`: provide only addresses, for all supported assets\r\n        - [X] `/:domain/amount`: provide only amounts owned for all supported assets\r\n        - [X] `/:domain/:asset` provide only (all) data for a specific asset\r\n        - [X] `/:domain/:asset/address` provide only address for a specific asset\r\n        - [X] `/:domain/:asset/amount` provide only amount owned for a specific asset\r\n        - [X] `/:domain/:asset/fiat` provide only value in USD of amount owned for a specific asset\r\n        - [X] `/:domain/net` provide only net worth\r\n- [X] Testing\r\n    - [X] Affirm implementation of all necessary error handling\r\n    - [X] Implement proper logging\r\n    - [X] Implement all necessary tests\r\n    - [X] Automate testing with GitHub workflows\r\n- [X] Implement Docker\r\n- [X] Fully document API\r\n\r\n## License\r\nAll original software within this repository is licensed under the GPL-3.0 License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsn0rp%2Ffinense","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsn0rp%2Ffinense","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsn0rp%2Ffinense/lists"}