|
| 1 | +# Binance Java Alpha Connector |
| 2 | + |
| 3 | +[](https://github.com/binance/binance-connector-java/issues) |
| 4 | +[](https://github.com/diffplug/spotless) |
| 5 | +[](https://central.sonatype.com/artifact/io.github.binance/binance-alpha) |
| 6 | + |
| 7 | +[](https://snyk.io/test/github/binance/binance-connector-java) |
| 8 | +[](https://opensource.org/licenses/MIT) |
| 9 | + |
| 10 | +This is a client library for the Binance Alpha API, enabling developers to interact programmatically with Binance Alpha. The library provides tools to access curated early-stage token data, track Alpha project metrics and integrate discovery-focused market information into applications through the REST API: |
| 11 | + |
| 12 | +- [REST API](./src/main/java/com/binance/connector/client/alpha/rest/api) |
| 13 | + |
| 14 | +## Table of Contents |
| 15 | + |
| 16 | +- [Supported Features](#supported-features) |
| 17 | +- [Installation](#installation) |
| 18 | +- [Documentation](#documentation) |
| 19 | +- [REST APIs](#rest-apis) |
| 20 | +- [Testing](#testing) |
| 21 | +- [Migration Guide](#migration-guide) |
| 22 | +- [Contributing](#contributing) |
| 23 | +- [License](#license) |
| 24 | + |
| 25 | +## Supported Features |
| 26 | + |
| 27 | +- REST API Endpoints: |
| 28 | + - `/bapi/defi/v1/*` |
| 29 | +- Inclusion of test cases and examples for quick onboarding. |
| 30 | + |
| 31 | +## Installation |
| 32 | + |
| 33 | +To use this library, ensure your environment is running Java version **11** or newer. |
| 34 | + |
| 35 | +Then add dependency to pom.xml: |
| 36 | + |
| 37 | +```xml |
| 38 | +<dependency> |
| 39 | + <groupId>io.github.binance</groupId> |
| 40 | + <artifactId>binance-alpha</artifactId> |
| 41 | + <version>1.1.0</version> |
| 42 | +</dependency> |
| 43 | +``` |
| 44 | + |
| 45 | +## Documentation |
| 46 | + |
| 47 | +For detailed information, refer to the [Binance API Documentation](https://developers.binance.com/docs/alpha). |
| 48 | + |
| 49 | +### REST APIs |
| 50 | + |
| 51 | +All REST API endpoints are available through the [`rest`](./src/main/java/com/binance/connector/client/alpha/rest) module. Note that some endpoints require authentication using your Binance API credentials. |
| 52 | + |
| 53 | +```java |
| 54 | +import com.binance.connector.client.alpha.rest.AlphaRestApiUtil; |
| 55 | +import com.binance.connector.client.alpha.rest.api.AlphaRestApi; |
| 56 | +import com.binance.connector.client.common.ApiException; |
| 57 | +import com.binance.connector.client.common.ApiResponse; |
| 58 | +import com.binance.connector.client.common.configuration.ClientConfiguration; |
| 59 | +import com.binance.connector.client.common.configuration.SignatureConfiguration; |
| 60 | + |
| 61 | +public static void main(String[] args) { |
| 62 | + ClientConfiguration clientConfiguration = AlphaRestApiUtil.getClientConfiguration(); |
| 63 | + SignatureConfiguration signatureConfiguration = new SignatureConfiguration(); |
| 64 | + signatureConfiguration.setApiKey("apiKey"); |
| 65 | + signatureConfiguration.setPrivateKey("path/to/private.key"); |
| 66 | + clientConfiguration.setSignatureConfiguration(signatureConfiguration); |
| 67 | + AlphaRestApi api = new AlphaRestApi(clientConfiguration); |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +More examples can be found in the [`examples/rest`](./../../examples/alpha/src/main/java/com/binance/connector/client/alpha/rest) folder. |
| 72 | + |
| 73 | +#### Configuration Options |
| 74 | + |
| 75 | +The REST API supports the following advanced configuration options: |
| 76 | + |
| 77 | +- `proxy`: Proxy configuration for http client. |
| 78 | +- `certificatePinner`: Certificate Pinner configuration for http client. |
| 79 | +- `connectTimeout`: Timeout for requests in milliseconds (default: 1000 ms). |
| 80 | +- `readTimeout`: Timeout for requests in milliseconds (default: 5000 ms). |
| 81 | +- `compression`: Enable response compression (default: true). |
| 82 | +- `retries`: Number of retry attempts for failed requests (default: 3). |
| 83 | +- `backoff`: Delay in milliseconds between retries (default: 200 ms). |
| 84 | +- `timeUnit`: TimeUnit to be returned by API (default MILLISECOND). |
| 85 | +- `apiKey`: Binance API Key |
| 86 | +- `secretKey`: Binance Secret Key, if using HMAC algorithm |
| 87 | +- `privateKey`: RSA or ED25519 private key for authentication. |
| 88 | +- `privateKeyPass`: Passphrase for the private key, if encrypted. |
| 89 | + |
| 90 | +##### Timeout |
| 91 | + |
| 92 | +You can configure a timeout for requests in milliseconds. If the request exceeds the specified timeout, it will be aborted. See the [Timeout example](./docs/rest-api/timeout.md) for detailed usage. |
| 93 | + |
| 94 | +##### Proxy |
| 95 | + |
| 96 | +The REST API supports HTTP/HTTPS proxy configurations. See the [Proxy example](./docs/rest-api/proxy.md) for detailed usage. |
| 97 | + |
| 98 | +##### Keep-Alive |
| 99 | + |
| 100 | +Enable HTTP keep-alive for persistent connections. See the [Keep-Alive example](./docs/rest-api/keepAlive.md) for detailed usage. |
| 101 | + |
| 102 | +##### Compression |
| 103 | + |
| 104 | +Enable or disable response compression. See the [Compression example](./docs/rest-api/compression.md) for detailed usage. |
| 105 | + |
| 106 | +##### Retries |
| 107 | + |
| 108 | +Configure the number of retry attempts and delay in milliseconds between retries for failed requests. See the [Retries example](./docs/rest-api/retries.md) for detailed usage. |
| 109 | + |
| 110 | +##### Key Pair Based Authentication |
| 111 | + |
| 112 | +The REST API supports key pair-based authentication for secure communication. You can use `RSA` or `ED25519` keys for signing requests. See the [Key Pair Based Authentication example](./docs/rest-api/key-pair-authentication.md) for detailed usage. |
| 113 | + |
| 114 | +##### Certificate Pinning |
| 115 | + |
| 116 | +To enhance security, you can use certificate pinning with the `httpsAgent` option in the configuration. This ensures the client only communicates with servers using specific certificates. See the [Certificate Pinning example](./docs/rest-api/certificate-pinning.md) for detailed usage. |
| 117 | + |
| 118 | +#### Error Handling |
| 119 | + |
| 120 | +The REST API provides detailed error types to help you handle issues effectively: |
| 121 | + |
| 122 | +- `ConnectorClientError`: General client error. |
| 123 | + |
| 124 | +See the [Error Handling example](./docs/rest-api/error-handling.md) for detailed usage. |
| 125 | + |
| 126 | +If `basePath` is not provided, it defaults to `https://api.binance.com`. |
| 127 | + |
| 128 | +## Testing |
| 129 | + |
| 130 | +To run the tests: |
| 131 | + |
| 132 | +```bash |
| 133 | +mvn -f clients/pom.xml -pl alpha test |
| 134 | +``` |
| 135 | + |
| 136 | +The tests cover: |
| 137 | + |
| 138 | +- REST API endpoints |
| 139 | +- Signature generation |
| 140 | + |
| 141 | +## Migration Guide |
| 142 | + |
| 143 | +If you are upgrading to the new modularized structure, refer to the [Migration Guide](./docs/rest-api/migration-guide.md) for detailed steps. |
| 144 | + |
| 145 | +## Contributing |
| 146 | + |
| 147 | +Contributions are welcome! |
| 148 | + |
| 149 | +Since this repository contains auto-generated code, we encourage you to start by opening a GitHub issue to discuss your ideas or suggest improvements. This helps ensure that changes align with the project's goals and auto-generation processes. |
| 150 | + |
| 151 | +To contribute: |
| 152 | + |
| 153 | +1. Open a GitHub issue describing your suggestion or the bug you've identified. |
| 154 | +2. If it's determined that changes are necessary, the maintainers will merge the changes into the main branch. |
| 155 | + |
| 156 | +Please ensure that all tests pass if you're making a direct contribution. Submit a pull request only after discussing and confirming the change. |
| 157 | + |
| 158 | +Thank you for your contributions! |
| 159 | + |
| 160 | +## License |
| 161 | + |
| 162 | +This project is licensed under the MIT License. See the [LICENSE](../../LICENSE) file for details. |
0 commit comments