{"id":18895666,"url":"https://github.com/binance/binance-futures-connector-java","last_synced_at":"2025-04-09T06:09:38.628Z","repository":{"id":64858301,"uuid":"573263425","full_name":"binance/binance-futures-connector-java","owner":"binance","description":"Simple Java connector to Binance Futures API","archived":false,"fork":false,"pushed_at":"2024-10-03T08:28:07.000Z","size":147,"stargazers_count":164,"open_issues_count":22,"forks_count":78,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-01T13:04:02.312Z","etag":null,"topics":["binance-api","connector","crypto","futures-market","java","library","real-time","trading"],"latest_commit_sha":null,"homepage":"","language":"Java","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/binance.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2022-12-02T03:37:56.000Z","updated_at":"2025-03-26T23:32:12.000Z","dependencies_parsed_at":"2023-02-09T14:16:31.970Z","dependency_job_id":"e08dc3da-dfb9-4956-a8c9-c97b2e5445ba","html_url":"https://github.com/binance/binance-futures-connector-java","commit_stats":{"total_commits":5,"total_committers":4,"mean_commits":1.25,"dds":0.6,"last_synced_commit":"665cfb871836b3167fa1100c16d7cdce35181cfc"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binance","download_url":"https://codeload.github.com/binance/binance-futures-connector-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987285,"owners_count":21028895,"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":["binance-api","connector","crypto","futures-market","java","library","real-time","trading"],"created_at":"2024-11-08T08:29:17.056Z","updated_at":"2025-04-09T06:09:38.611Z","avatar_url":"https://github.com/binance.png","language":"Java","readme":"# Binance Futures Public API connector Java\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code Style](https://img.shields.io/badge/code%20style-checkstyle-yellow)](https://checkstyle.org/checks.html)\n\nThis is a lightweight library that works as a connector to the [Binance Futures API](https://developers.binance.com/docs/derivatives/Introduction)\n\n- Supported APIs:\n  - `/fapi/*`\n  - `/dapi/*`\n  - `/futures/*`\n  - USD-M Futures Websocket Market Stream\n  - COIN-M Futures Websocket Market Stream\n  - USD-M Futures User Data Stream\n  - COIN-M Futures User Data Stream\n- Test cases and examples\n\n## Installation\nReplace `LATEST_VERSION` with the latest version number and paste the snippet below in `pom.xml`\n```\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.binance\u003c/groupId\u003e\n    \u003cartifactId\u003ebinance-futures-connector-java\u003c/artifactId\u003e\n    \u003cversion\u003eLATEST_VERSION\u003c/version\u003e\n\u003c/dependency\u003e\n```\nRun `mvn install` where `pom.xml` is located to install the dependency.\n\n### Run Example\nThe examples are located under **src/test/java/examples**. Before running the examples,\nset up your **API_KEY** and **SECRET_KEY** in `PrivateConfig.java`. This configuration file is only used for examples,\nyou should reconfigure the API_KEY and SECRET_KEY when using the library.\n\n### RESTful APIs\n\nThe endpoints are categorized according to the following API documentations:\n- [Binance USDⓈ-M Futures](https://developers.binance.com/docs/derivatives/usds-margined-futures/general-info)\n- [Binance COIN-M Futures](https://developers.binance.com/docs/derivatives/coin-margined-futures/general-info)\n\nEach object corresponds to its category which will be used to call its respective endpoints.\n\n\n| Category        |     Object       |\n| --------------- | ---------------- |\n| Account/Trades  | account          |\n| Market Data     | market           |\n| User Data       | userData         |\n| Portfolio Margin| portfolioMargin  |\n\n\u003cbr\u003e\n\n#### Market Endpoint: Exchange Information\n```java\n// UM-Futures\nUMFuturesClientImpl client = new UMFuturesClientImpl();\nString result = client.market().exchangeInfo();\n\n// CM-Futures\nCMFuturesClientImpl client = new CMFuturesClientImpl();\nString result = client.market().exchangeInfo();\n```\n\n#### Trade Endpoint: Testing a new order\n```java\nLinkedHashMap\u003cString,Object\u003e parameters = new LinkedHashMap\u003cString,Object\u003e();\n\nUMFuturesClientImpl client = new UMFuturesClientImpl(PrivateConfig.API_KEY, PrivateConfig.SECRET_KEY);\n\nparameters.put(\"symbol\",\"BTCUSDT\");\nparameters.put(\"side\", \"SELL\");\nparameters.put(\"type\", \"LIMIT\");\nparameters.put(\"timeInForce\", \"GTC\");\nparameters.put(\"quantity\", 0.01);\nparameters.put(\"price\", 9500);\n\nString result = client.trade().testNewOrder(parameters);\n```\n\n### Testnet\n\n`/fapi/*` and `/dapi/*` endpoints can be tested in [Futures Testnet](https://testnet.binancefuture.com). You can use it by changing the base URL:\n\n```java\nLinkedHashMap\u003cString,Object\u003e parameters = new LinkedHashMap\u003c\u003e();\n\nUMFuturesClientImpl client = new UMFuturesClientImpl(PrivateConfig.TESTNET_API_KEY, PrivateConfig.TESTNET_SECRET_KEY);\nString result = client.market().time();\n```\n\n### Base URL\nIt's recommended to pass in the `baseUrl` parameter.\nIf not provided, the default baseUrl for USD-M Futures is `https://fapi.binance.com`\u003cbr/\u003e\nIf not provided, the default baseUrl for COIN-M Futures is `https://dapi.binance.com`\u003cbr/\u003e\n\n### Optional parameters\n\nAll parameters are read from a `LinkedHashMap\u003cString,Object\u003e` object where `String` is the name of the parameter and `Object` is the value of the parameter. The parameters should follow their exact naming as in the API documentation.\u003cbr\u003e\n```java\nLinkedHashMap\u003cString,Object\u003e parameters = new LinkedHashMap\u003cString,Object\u003e();\n\nparameters.put(\"symbol\",\"BTCUSDT\");\nparameters.put(\"side\", \"SELL\");\nparameters.put(\"type\", \"LIMIT\");\nparameters.put(\"timeInForce\", \"GTC\");\nparameters.put(\"quantity\", 0.01);\nparameters.put(\"price\", 9500);\n```\n\n### Response MetaData\n\nThe Binance API server provides weight usages in the headers of each response. This value can be return by\ncalling `setShowLimitUsage` and setting it to `true`.\n```java\nUMFuturesClientImpl client = new UMFuturesClientImpl();\nclient.setShowLimitUsage(true);\nString result = client.market().time();\nlogger.info(result);\n```\noutput:\n```\nINFO: {\"data\":\"{\"serverTime\":1633434339494}\",\"x-mbx-used-weight\":\"1\",\"x-mbx-used-weight-1m\":\"1\"}\n```\n\n### Proxy\nHTTP Proxy is supported.\n\nTo set it up, call `setProxy()` with `ProxyAuth` and before submitting requests to binance:\n\n```java\nCMFuturesClientImpl client = new CMFuturesClientImpl();\nProxy proxyConn = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(\"127.0.0.1\", 8080));\nProxyAuth proxy = new ProxyAuth(proxyConn, null);\n\nclient.setProxy(proxy);\nlogger.info(client.market().time());\n```\n\nFor authenticated `Proxy`, define `ProxyAuth` with [`Authenticator` from `okhttp3`](https://square.github.io/okhttp/3.x/okhttp/index.html?okhttp3/Authenticator.html):\n\n```java\nCMFuturesClientImpl client = new CMFuturesClientImpl();\nProxy proxyConn = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(\"127.0.0.1\", 8080));\n    Authenticator auth = new Authenticator() {\n    public Request authenticate(Route route, Response response) throws IOException {\n        if (response.request().header(\"Proxy-Authorization\") != null) {\n            return null; // Give up, we've already failed to authenticate.\n          }\n      \n        String credential = Credentials.basic(\"username\", \"password\");\n        return response.request().newBuilder().header(\"Proxy-Authorization\", credential).build();\n        \n    }\n};\nProxyAuth proxy = new ProxyAuth(proxyConn, auth);\n\nclient.setProxy(proxy);\nlogger.info(client.market().time());\n```\n\nTo undo `Proxy`, use `unsetProxy()` before submitting requests to binance:\n\n```java\nclient.unsetProxy();\nlogger.info(client.market().time());\n```\n\nComplete examples are available to the following folders:\n- `test/java/examples/cm_futures/proxy`\n- `test/java/examples/um_futures/proxy`\n\n### Logging\n\n`ch.qos.logback` is used for logging in this connector. The configuration xml file can be found under\n`src/main/resources`.\n\n### Error\n\nThere are 3 types of error which may be thrown by this library.\n\n- `BinanceConnectorException`\n  - This is thrown when there is a validation error for parameters.For instance, mandatory parameter not sent. This error will be thrown before the request is sent to the server.\n- `BinanceClientException`\n  - This is thrown when server returns `4XX`, it's an issue from client side.\n  - The error consists of these 3 objects which will help in debugging the error:\n    - `httpStatusCode` - HTTP status code\n    - `errorCode` - API Server's error code, e.g. `-1102`\n    - `errMsg` - API Server's error message, e.g. `Unknown order sent.`\n- `BinanceServerException`\n  - This is thrown when server returns `5XX`, it's an issue from server side.\n```java\ntry {\n      String result = client.trade().newOrder(parameters);\n      logger.info(result);\n    } catch (BinanceConnectorException e) {\n      logger.error(\"fullErrMessage: {}\", e.getMessage(), e);\n    } catch (BinanceClientException e) {\n      logger.error(\"fullErrMessage: {} \\nerrMessage: {} \\nerrCode: {} \\nHTTPStatusCode: {}\",\n      e.getMessage(), e.getErrMsg(), e.getErrorCode(), e.getHttpStatusCode(), e);\n    }\n```\n\n### Websocket\n\n```java\nUMWebsocketClientImpl client = new UMWebsocketClientImpl(); // defaults to production websocket URL unless stated\nint streamID1 = client.aggTradeStream(\"btcusdt\",((event) -\u003e {\n    System.out.println(event);\n}));\n\n//Combining Streams\nArrayList\u003cString\u003e streams = new ArrayList\u003c\u003e();\nstreams.add(\"btcusdt@trade\");\nstreams.add(\"bnbusdt@trade\");\n\nint streamID2 = client.combineStreams(streams, ((event) -\u003e {\n    System.out.println(event);\n}));\n\n//Listening to User Data Stream\nint streamID3 = client.listenUserStream(listenKey, ((event) -\u003e {\n  System.out.println(event);\n}));\n\n//Closing a single stream\nclient.closeConnection(streamID1); //closes aggTradeStream-btcusdt\n\n//Closing all streams\nclient.closeAllConnections();\n```\nMore websocket examples are available in the `test/examples` folder\n\n\n### Test\n`mvn clean test`\n\n## Contributing\n\nContributions are welcome.\u003cbr/\u003e\nIf you've found a bug within this project, please open an issue to discuss what you would like to change.\u003cbr/\u003e\nIf it's an issue with the API, please open a topic at [Binance Developer Community](https://dev.binance.vision)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinance%2Fbinance-futures-connector-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinance%2Fbinance-futures-connector-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinance%2Fbinance-futures-connector-java/lists"}