# Get started

To request the SDK, contact the [Ripple support team](/products/custody/v1.19/support/get-support).

The SDK is provided as a Maven dependency and can be added to a JVM project.

The SDK doesn't implement a signer service, which directly depends on the key management system used by the service consumer. You first need to implement this signer service as a Java class before using the SDK. For more information, see [Implement the signer service](#implement-the-signer-service).

An example signer implementation is available upon request from the Ripple support team.

## Prerequisites

To use the SDK, you need access to a working instance of Ripple Custody.

## Install the SDK

To install the SDK, run the following command:


```bash
mvn install:install-file -Dfile=./sdk-{sdk-version}.jar -DgroupId=com.metaco -DartifactId=sdk -Dversion={sdk-version} -Dpackaging=jar -DpomFile=./sdk-{sdk-version}.pom
```

When the Java project is created, configure the SDK dependency project for Maven use by adding a dependency in the following format:


```xml
<dependencies>
    <dependency>
        <groupId>com.metaco</groupId>
        <articatId>sdk</artifactId>
        <version>{sdk-version}</version>
    </dependency>
</dependencies>
```

The version number must match the SDK package.

## Implement the signer service

The SDK does not natively implement methods to manage user keys and perform signatures. This choice is made for security reasons, so that the SDK code does not have direct access to private keys. This means that you must create your own key pair and signature handling logic.

The signer interface is the interface that the SDK uses to communicate with user key and signer implementation. This
is passed to the SDK when a `HarmonizeContext` instance is loaded, as follows:


```java
var harmonizeCtx = HarmonizeContext.load(signer);
// we get the Ripple Custody instance from the context
var harmonize = harmonizeCtx.harmonize;
```

You can switch in a new signer, for example for a new user instance, with the following command:


```java
var newHarmonizeCtx = harmonizeCtz.switchSigner(newSigner);
```

You can request an example test signer template from the Ripple support team.

The signer implementation is SDK user-specific.
To implement the signer, use the provided `Signer` interface.

### JSON message serialization

Before a message is signed, you need to ensure it is converted to canonical JSON format.
This ensures that hashes are repeatable from the JSON encoded data. The Ripple Custody API performs the same operation before checking the hash.

All entities returned and used by the SDK implement the `.toJson()` method, which produces the correctly canonicalized JSON output, in the appropriate format for the user to apply the signature.
You can optionally use the `GsonUtils` helper class to serialize any messages for correct signing.

## Configure the SDK

You can load the configuration from the file system or set it with environment variables. The SDK searches for a configuration in the following order:

* A `harmonize.json` file in the home directory.
* A `harmonize.json` file in the directory of command execution.
* A user-provided configuration file, via the `--conf` flag.
* A file specified using the environment variable `HARMONIZE_CONF`.
* Direct environment variables.


You can overwrite any configuration variable with an environment variable.

The configuration variables are listed in the following table:

| Name | Description | Required |
|  --- | --- | --- |
| `GATEWAY_URL` | URL that points to the API gateway | Yes |
| `OAUTH_URL` | URL that points to the OAuth token service | Yes |
| `OAUTH_CLIENT_ID` | OAuth client ID | Yes |
| `OAUTH_CLIENT_SECRET` | OAuth client secret | Yes |
| `TIMEOUT` | HTTP timeout | No |
| `HTTP_VERSION` | HTTP version to use | No |
| `USER_ID` | User ID to use for performing SDK operations | Yes |
| `OPEN_API_VALIDATE_WARN_ONLY` | Whether to use API validation. If `true`, API validation is turned off. Default is `false`. | No |
| `OPEN_API_VALIDATE_STRICT_ENUMS` | Whether to use ENUM validation. If `true`, API ENUM validation is turned off. Default is `false`. | No |


### JSON example

The following example shows a JSON configuration file:


```json
{
  "GATEWAY_URL": "<>",
  "OAUTH_URL": "<>",
  "OAUTH_CLIENT_ID": "<>",
  "OAUTH_CLIENT_SECRET": "<>",
  "TIMEOUT": "<>",
  "HTTP_VERSION": "<>",
  "USER_ID": "<The user id>",
  "OPEN_API_VALIDATE_WARN_ONLY": "boolean",
  "OPEN_API_VALIDATE_STRICT_ENUMS": "boolean"
}
```