{"id":23038454,"url":"https://github.com/tdjsnelling/orderbook","last_synced_at":"2026-05-08T13:37:18.241Z","repository":{"id":76807925,"uuid":"400306799","full_name":"tdjsnelling/orderbook","owner":"tdjsnelling","description":"Simple Node.js FIFO order matching engine, powered by Redis","archived":false,"fork":false,"pushed_at":"2022-03-28T21:09:57.000Z","size":185,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T23:31:52.263Z","etag":null,"topics":["matching-engine","nodejs","orderbook","protobuf","redis","trading","websocket"],"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/tdjsnelling.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":"2021-08-26T21:10:37.000Z","updated_at":"2025-01-06T16:29:20.000Z","dependencies_parsed_at":"2023-07-04T22:16:26.554Z","dependency_job_id":null,"html_url":"https://github.com/tdjsnelling/orderbook","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tdjsnelling/orderbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Forderbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Forderbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Forderbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Forderbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tdjsnelling","download_url":"https://codeload.github.com/tdjsnelling/orderbook/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Forderbook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32782904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"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":["matching-engine","nodejs","orderbook","protobuf","redis","trading","websocket"],"created_at":"2024-12-15T18:18:54.630Z","updated_at":"2026-05-08T13:37:18.233Z","avatar_url":"https://github.com/tdjsnelling.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# orderbook\n\nSimple Node.js FIFO order matching engine, powered by Redis\n\n## Running\n\n```\n$ yarn install\n$ yarn build\n$ yarn start\n```\n\nEnsure you also have a Redis server running.\n\n### Environment variables\n\n.env file will be picked up automatically.\n\n```dotenv\n# alternatively BASE_URL=ws://localhost\nBASE_URL=wss://example.com\n\n# default is 9696\nPORT=5000\n\nREDIS_HOST=localhost\nREDIS_PORT=6379\n# REDIS_AUTH=password\n```\n\n## Using\n\nOnce started, the server provides a websocket endpoint on the configured port.\n\nWhen connecting to the websocket, the server expects a URL query parameter `user` to identify the connection. For example, you could connect to `wss://example.com/?user=alice`.\n\nThe engine itself provides no method for authentication. Any client can connect to the websocket with any unique ID. If an ID is already in use, new connections with the same ID will be rejected.\n\nOnce connected to, the endpoint expects messages in the format:\n\n```\nmessageType|data\n```\n\nWhere:\n* `messageType` is an integer representing the type of message being sent, as defined in [src/handleMessage.js](https://github.com/tdjsnelling/orderbook/blob/master/src/handleMessage.js#L5)\n* `data` is a base64 string containing the protobuf encoded message\n\n### Message types\n\nThere are 3 different message types.\n\n#### Order\n\nThe main message type used to push new orders. An order message consists of 4 parts:\n\n* `uid`: the identifier of the user submitting the order\n* `side`: whether the order is buy (0) or sell (1)\n* `symbol`: the symbol or identifier of the item the order is for, e.g. 'BTC/GBP' or 'AAPL'\n* `price`: the desired buy/sell price, in the smallest denomination. This field should not contain decimals\n\nTo submit an order, a protobuf message must be assembled from the above fields, and then sent as a base64 string, using the `order` message type.\n\n##### Example\n\nThe order:\n\n```json\n{\n  \"uid\": \"alice\",\n  \"side\": 0,\n  \"symbol\": \"BTC/GBP\",\n  \"price\": 4088820\n}\n```\n\nShould be sent as:\n\n```\n0|CgVhbGljZRAAGgNCVEMhAAAAAPoxT0E=\n```\n\nOn the websocket you will receive a JSON result either saying your order has been submitted and is waiting to be matched or that it has been matched immediately.\n\nIf you have previously submitted an order and another client matches it, you will receive a similar JSON message on your open websocket.\n\n#### Query\n\nA query message allows you to see how many buy or sell orders currently exist for a particular symbol.\n\nQuery messages require a `uid`, `side`, and `symbol`.\n\nYou will receive a JSON response listing the number of buy or sell orders at each `price`.\n\nFor example, if the following orders are made:\n\n```\nbuy BTC/GBP 1000\nsell BTC/GBP 2000\nbuy BTC/GBP 1001\nbuy BTC/GBP 1000\n```\n\nQuerying `buy BTC/GBP` would give the response:\n\n```json\n{\n  \"1000\": 2,\n  \"1001\": 1\n}\n```\n\nAnd querying `sell BTC/GBP` would give the response:\n\n```json\n{\n  \"2000\": 1\n}\n```\n\n#### View\n\nA view message allows you to view all buy or sell orders for a symbol at a specific price. This data includes the timestamp of when an order was placed and the ID of the client that placed it.\n\nView messages require a `uid`, `side`, `symbol` and `price`. Additionally, they also require `start` and `stop` fields, integers determining how many orders should be returned.\n\nA `start` of `0` and `stop` of `4` will return the first 5 orders, oldest first. `5 10` will return the next 5, and so on. If `stop` is greater than the max index, then `start` until the final order will be returned.\n\n### Responses\n\nResponses are JSON. They will always contain a `type` field, and either a `data` or `error` field.\n\n## Order statistics\n\nRedis also stores the fields `TOTAL_ORDERS` and `TOTAL_MATCHED` to track the number of orders processed.\n\n## Example client\n\nThis repo provides a basic example client in `tools/client`.\n\nIt can be started with:\n\n```\n$ yarn client -s \"ws://localhost:9696/?user=alice\"\n```\n\nThen commands can be issued, and messages/responses will be printed:\n\n```\n? alice\u003e order buy BTC/GBP 1000\n\u003e 0|CgVhbGljZRAAGgdCVEMvR0JQIQAAAAAAQI9A\n\u003c {\"type\":\"order\",\"message\":\"Order submitted to queue\",\"data\":{\"order\":\"0:BTC/GBP@1000\",\"uid\":\"alice\",\"ts\":1647977737275,\"hash\":\"3a45d46\"}}\n? alice\u003e query buy BTC/GBP 1000\n\u003e 1|CgVhbGljZRAAGgdCVEMvR0JQ\n\u003c {\"type\":\"query\",\"data\":{\"1000\":1}}\n? alice\u003e view buy BTC/GBP 1000 0 0\n\u003e 2|CgVhbGljZRAAGgdCVEMvR0JQIQAAAAAAQI9AKAAwAA==\n\u003c {\"type\":\"query\",\"data\":[{\"uid\":\"alice\",\"ts\":1647977737275,\"hash\":\"3a45d46\"}]}\n```\n\n## License\n\nGNU GPL v3\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdjsnelling%2Forderbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftdjsnelling%2Forderbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdjsnelling%2Forderbook/lists"}