# Integrate via SDK

Ripple Custody (Vault) provides client SDKs that wrap the REST API. This quickstart takes you from installing an SDK to submitting your first intent. Use it when you're starting a new integration in TypeScript, Java, or Python.

Each SDK handles authentication, intent signing and submission, response-signature verification, and pagination. Your code calls typed methods instead of sending raw HTTP requests.

| SDK | Package | Runtime |
|  --- | --- | --- |
| TypeScript | `@ripple/ripple-custody-client-lib-typescript` | Node.js 22.19 or later. Promise-based API. |
| Java | `com.ripple.custody.platform.contrib:ripple-custody-client-lib-java` | Java 17 or later. Synchronous API. |
| Python | `ripple_custody_client_lib_python` | Python 3.9 or later. Synchronous and asynchronous clients. |


For a feature comparison and the full reference, see [Client SDKs](/pt-br/products/custody/developer-experience/sdks).

Pre-release versions
The SDKs are pre-1.0. Their APIs may change between releases. Pin the exact version that you test with.

## Prerequisites

Before you start, you must have:

- Access to a running Ripple Custody (Vault) instance, including its API base URL and the URL of its OpenID Connect (OIDC) issuer.
- A registered user with a P-256 signing key pair. You keep the private key in a PEM file, and the platform holds the public key. To create and register the key pair, see [Generate a key pair and register a public key](/pt-br/products/custody/identity-and-access/authentication/generate-api-keys-and-register).
- The user ID and domain ID of that registered user.
- The notary API public key for your environment. By default, the SDKs verify the signature on API responses, and they require this key to do so. Get the key from your Ripple Custody (Vault) administrator.


## Install the SDK

Ripple provides the SDK packages as files. To get the package for your language, contact the [Ripple support team](/pt-br/products/custody/support/get-support). Then install the SDK from the file.

File names include the SDK version. In the following commands, replace `{version}` with the version that you received.

TypeScript
Install the package from the `.tgz` file:

```bash
npm install ./ripple-ripple-custody-client-lib-typescript-{version}.tgz
```

npm records the dependency in `package.json` as a `file:` path. Keep the `.tgz` file where your build can reach it, for example in your repository.

To sign with AWS Key Management Service (KMS) or Azure Key Vault instead of a local key file, also install the provider SDK. The TypeScript SDK loads it on demand:

```bash
npm install @aws-sdk/client-kms                     # AWS KMS
npm install @azure/keyvault-keys @azure/identity    # Azure Key Vault
```

Java
Install the JAR and its Project Object Model (POM) file into your local Maven repository. The POM lists the SDK's dependencies, so your build tool resolves them from Maven Central:

```bash
mvn install:install-file \
  -Dfile=ripple-custody-client-lib-java-{version}.jar \
  -DpomFile=ripple-custody-client-lib-java-{version}.pom
```

Then add the dependency to your build. For Gradle:

```groovy
repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    implementation 'com.ripple.custody.platform.contrib:ripple-custody-client-lib-java:{version}'
}
```

For Maven:

```xml
<dependency>
    <groupId>com.ripple.custody.platform.contrib</groupId>
    <artifactId>ripple-custody-client-lib-java</artifactId>
    <version>{version}</version>
</dependency>
```

For a shared build, such as a CI pipeline, publish the JAR and POM to your organization's Maven repository instead of to each machine's local repository.

Python
Install the package from the wheel file:

```bash
pip install ./ripple_custody_client_lib_python-{version}-py3-none-any.whl
```

The Python SDK packages optional features as extras. To install an extra, add it to the file name. Install only the extras that you use:

```bash
pip install "./ripple_custody_client_lib_python-{version}-py3-none-any.whl[async]"           # AsyncCustodyClient
pip install "./ripple_custody_client_lib_python-{version}-py3-none-any.whl[kms-hashicorp]"   # HashiCorp Vault Transit signing
pip install "./ripple_custody_client_lib_python-{version}-py3-none-any.whl[kms-aws]"         # AWS KMS signing (Python 3.10 or later)
pip install "./ripple_custody_client_lib_python-{version}-py3-none-any.whl[kms-azure]"       # Azure Key Vault signing
pip install "./ripple_custody_client_lib_python-{version}-py3-none-any.whl[kms-all]"         # All three KMS providers
pip install "./ripple_custody_client_lib_python-{version}-py3-none-any.whl[evm]"             # EVM contract-call encoding
```

pip installs the SDK's own dependencies from PyPI.

### Use the command-line helper

The TypeScript and Python packages install a `ripple-custody` command. The Java SDK has no command-line helper.

| Command | TypeScript | Python |
|  --- | --- | --- |
| `ripple-custody quickstart` | Prints the getting-started steps. | Creates a project directory with a `config.toml`, a new signing key, and a runnable script. |
| `ripple-custody keygen` | Generates a signing key pair. Choose the curve with `--curve` (`P-256`, `secp256k1`, or `Ed25519`) and write the private key to a file with `--out`. | Generates a signing key pair. Choose the key type with `--key-type` (`Secp256r1`, `Secp256k1`, or `Ed25519`) and write the private key to a file with `--out`. |
| `ripple-custody config init` | Copies the configuration template to `./config.toml`, or to the path you pass. | Writes an annotated `config.toml`, plus `.envrc` and `.gitignore` stubs, to the current directory. |
| `ripple-custody doctor` | Checks your configuration and connectivity to the cluster. | Checks your installation, configuration, and connectivity. Add `--json` for output you can attach to a support request. |


Both `keygen` commands print the public key in base64-encoded DER (SPKI) format. The platform expects this format when you register a key.

If you installed the TypeScript SDK locally, run the command through `npx`, for example `npx ripple-custody doctor`.

## Configure the SDK

All three SDKs read a `config.toml` file and `RC_*` environment variables. An environment variable always overrides the matching value in the file. By default, each SDK looks for `config.toml` at the path in `RC_CONFIG_FILE`, then in the current working directory, then at `~/.config/ripple-custody/config.toml`.

All three SDKs use the same key names, so the same file works in each language. Create a `config.toml` file like the following, and replace the placeholders with your instance's URLs, your IDs, and the notary API public key:

```toml
api_base_url          = "https://<api-host>"
oidc_issuer_url       = "https://<auth-host>/realms/<realm>"
private_key_file      = "/path/to/signing-key.pem"
rc_user_id            = "<your-user-id>"
rc_domain_id          = "<your-domain-id>"
notary_api_public_key = "<notary-api-public-key>"
```

Don't set `client_id` when you sign with a private key. The SDKs treat `client_id` as half of a client-credentials pair, and the TypeScript and Python SDKs fail unless you also supply a client secret. All three SDKs reject keys in `config.toml` that they don't recognize.

If you know the exact token endpoint, set `token_endpoint` in place of `oidc_issuer_url`.

To configure the SDK from the environment only, set the matching environment variables instead. The variable names are the same in all three SDKs:

```bash
export RC_API_BASE_URL="https://<api-host>"
export RC_OIDC_ISSUER_URL="https://<auth-host>/realms/<realm>"
export RC_PRIVATE_KEY_FILE="/path/to/signing-key.pem"
export RC_USER_ID="<your-user-id>"
export RC_DOMAIN_ID="<your-domain-id>"
export RC_NOTARY_API_PUBLIC_KEY="<notary-api-public-key>"
```

### Protect secrets

In the preceding examples, `config.toml` holds no secrets, so you can keep it in version control. Keep secrets out of the file:

- **Private key.** The SDK reads the key from the file path in `private_key_file` or `RC_PRIVATE_KEY_FILE`. The key itself never appears in the configuration. Restrict the key file's permissions so that only your application's user can read it. Both `keygen` commands write the file with mode `0600`. For production, sign with a KMS instead of a local file. For more information, see [Authentication and signing](/pt-br/products/custody/developer-experience/sdks/authentication-and-signing).
- **Client secret.** If you use the client-credentials grant, set the secret in the `RC_CLIENT_SECRET` environment variable. The Python SDK reads the secret only from `RC_CLIENT_SECRET`. The TypeScript SDK accepts `client_secret` in `config.toml` but logs a warning when you set it there. The Java SDK rejects `client_secret` in the file. Don't commit a file that holds the secret.


For every setting, including TLS and mutual TLS settings, see [Configure the SDK](/pt-br/products/custody/developer-experience/sdks/configuration).

## Create a client

Load the configuration and create a client. If the configuration is incomplete, this step fails immediately instead of on the first API call. For example, it fails if response verification is on and you haven't set a notary API public key.

The following code loads `config.toml` from the default location and creates a client:

TypeScript
```typescript
import {
  CustodyClient,
  loadConfiguration,
} from '@ripple/ripple-custody-client-lib-typescript';

const client = new CustodyClient(loadConfiguration());
```

To load a file from another location, pass its path: `loadConfiguration('/etc/custody/config.toml')`.

Java
```java
import com.ripple.custody.CustodyClient;
import com.ripple.custody.CustodyClientConfig;

CustodyClientConfig config = CustodyClientConfig.loadConfiguration();
CustodyClient client = CustodyClient.fromConfig(config);
```

`CustodyClient.fromConfig` reads the private key, chooses the OAuth grant, and builds the HTTP client for you. To load a file from another location, pass its path: `CustodyClientConfig.loadConfiguration(Path.of("/etc/custody/config.toml"))`.

Python
```python
from ripple_custody_client_lib_python import CustodyClient, load_configuration

config = load_configuration()
client = CustodyClient(config)
```

To load a file from another location, pass its path: `load_configuration("/etc/custody/config.toml")`.

The SDK obtains and refreshes OAuth access tokens for you.

## Make a first read call

List the domains that your user can see. A successful call confirms that authentication and response verification both work:

TypeScript
```typescript
const page = await client.governance.domains.list({ limit: 5 });
const domains = Array.isArray(page) ? page : page.items;
for (const domain of domains) {
  console.log(`${domain.data.id}: ${domain.data.alias}`);
}
```

`list()` returns one page by default. Pass `autoPaginate: true` to get every item as a flat array instead.

Java
```java
import com.ripple.custody.models.CoreTrustedDomainsCollection;

CoreTrustedDomainsCollection domains = client.governance().domains().list(5, null);
domains.getItems().forEach(d ->
    System.out.println(d.getData().getId() + ": " + d.getData().getAlias()));
```

Python
```python
result = client.governance.domains.list(limit=5)
for domain in result.items or []:
    print(f"{domain.data.id}: {domain.data.alias}")
```

For a complete program, see example `00` (getting started). To get the examples, see [Examples](/pt-br/products/custody/developer-experience/sdks#examples).

## Submit a first intent

You make changes in Ripple Custody (Vault) by submitting signed intents. The SDK builds the intent, signs it with your key, submits it, and returns a pending intent that you can wait on.

The following example proposes a new user with the `viewer` role. Your user must have permission to create users in the domain. The new user generates their own key pair and gives you only the public key, in base64-encoded DER format. Replace `<new-user-public-key>` with that key:

TypeScript
```typescript
const pending = await client.governance.users.create(
  'new-user@example.com',
  '<new-user-public-key>',
  ['viewer'],
  { loginIds: [{ id: 'new-user@example.com', providerId: 'harmonize' }] },
);

await pending.waitAccepted(30_000);   // timeout in milliseconds
await pending.waitExecuted(120_000);
console.log(`Intent ${pending.intentId} executed`);
```

Java
```java
import com.ripple.custody.PendingIntent;
import com.ripple.custody.models.CoreLoginId;
import java.util.List;
import java.util.Map;

PendingIntent pending = client.governance().users().create(
    config.getDefaultDomainId(),
    null,                                   // let the SDK generate the user ID
    "new-user@example.com",
    "<new-user-public-key>",
    List.of("viewer"),
    List.of(new CoreLoginId().id("new-user@example.com").providerId("harmonize")),
    Map.of());

pending.waitAccepted(30);                   // timeout in seconds
var intent = pending.waitExecuted(120);
if (!"Executed".equals(String.valueOf(intent.getData().getState().getStatus()))) {
    throw new IllegalStateException("Intent did not execute: " + intent.getData().getState().getStatus());
}
System.out.println("Intent " + pending.getIntentId() + " executed");
```

Python
```python
pending = client.governance.users.create(
    alias="new-user@example.com",
    public_key="<new-user-public-key>",
    roles=["viewer"],
    login_ids=[{"id": "new-user@example.com", "provider_id": "harmonize"}],
)

pending.wait_accepted(timeout=30)    # timeout in seconds
intent = pending.wait_executed(timeout=120)
if intent.data.state.status != "Executed":
    raise RuntimeError(f"Intent did not execute: {intent.data.state.status}")
print(f"Intent {pending.intent_id} executed")
```

The two waits track the two stages of an intent:

- **Wait accepted** returns when the platform accepts the request and creates the intent.
- **Wait executed** waits for a final intent state. An intent can execute after it collects the approvals its policy requires, or end in `Failed`, `Rejected`, or `Expired`. In TypeScript, the wait fails unless the intent executed. In Java and Python, it returns the intent in whatever final state it reaches, so check the status before reporting success or starting a dependent operation. In all SDKs, the wait fails if the timeout expires.


For a complete program, see example `10` (create user). To get the examples, see [Examples](/pt-br/products/custody/developer-experience/sdks#examples).

For approvals, rejections, and transaction intents, see [Work with intents](/pt-br/products/custody/developer-experience/sdks/intents).

## Close the client

When you're done, close the client to release its network connections:

TypeScript
```typescript
await client.close();
```

Java
The Java client has no `close()` method and holds no resources that you need to release.

Python
```python
client.close()
```

You can also use the client as a context manager, which closes it for you:

```python
with CustodyClient(config) as client:
    ...
```

## Next steps

- [Client SDKs](/pt-br/products/custody/developer-experience/sdks): compare SDK features by language.
- [Examples](/pt-br/products/custody/developer-experience/sdks#examples): get runnable example programs for common tasks.
- [Agent skills](/pt-br/products/custody/developer-experience/sdks#agent-skills): help an AI coding assistant write code with the SDK.
- [Configure the SDK](/pt-br/products/custody/developer-experience/sdks/configuration): every configuration key and environment variable.
- [Authentication and signing](/pt-br/products/custody/developer-experience/sdks/authentication-and-signing): client credentials, key types, and KMS-backed signers.
- [HashiCorp Vault](/pt-br/products/custody/developer-experience/sdks/hashicorp-vault): sign with a Vault Transit key.
- [Work with intents](/pt-br/products/custody/developer-experience/sdks/intents): wait, approve, and reject intents.
- [Response verification](/pt-br/products/custody/developer-experience/sdks/response-verification): how the SDKs verify API responses.
- [Errors and HTTP behavior](/pt-br/products/custody/developer-experience/sdks/errors-and-http): exception types, timeouts, and retries.
- [Migrate from the legacy Java SDK](/pt-br/products/custody/developer-experience/sdks/migrate-from-legacy-java-sdk): move from the `com.metaco` SDK.