# Client SDKs

The Ripple Custody client SDKs wrap the REST API in typed, language-native clients. This page lists the available SDKs and compares their features, so you can choose an SDK or check what yours supports.

Compared with calling the API directly, an SDK:

- Obtains and refreshes OAuth access tokens, using either a signed challenge or client credentials.
- Builds intents, canonicalizes and signs them with your key, submits them, and returns a pending intent you can wait on, approve, or reject.
- Verifies recognized signed response envelopes by default, with [language-specific exceptions](/pt-br/products/custody/developer-experience/sdks/response-verification#verification-limits).
- Validates destination addresses and other inputs before it sends anything.
- Pages through list results for you.


To install an SDK and make your first call, see [Integrate via SDK](/pt-br/products/custody/get-started/integrate-via-sdk).

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

## Available SDKs

| Language | Package | Version | Runtime | Programming model |
|  --- | --- | --- | --- | --- |
| TypeScript | `@ripple/ripple-custody-client-lib-typescript` | 0.5.0 | Node.js 22.19 or later | Promise-based (`async`/`await`) |
| Java | `com.ripple.custody.platform.contrib:ripple-custody-client-lib-java` | 0.2.0 | Java 17 or later | Synchronous |
| Python | `ripple_custody_client_lib_python` | 0.5.6 | Python 3.9 or later | Synchronous (`CustodyClient`) and asynchronous (`AsyncCustodyClient`) |


Ripple provides the packages as files. To get them, contact the [Ripple support team](/pt-br/products/custody/support/get-support). For installation steps, see [Integrate via SDK](/pt-br/products/custody/get-started/integrate-via-sdk#install-the-sdk).

## Feature support

| Feature | TypeScript | Java | Python |
|  --- | --- | --- | --- |
| Configuration from `config.toml` and `RC_*` environment variables | Yes | Yes | Yes |
| Signed-challenge authentication (private key) | Yes | Yes | Yes |
| Client-credentials authentication | Yes | Yes | Yes |
| Local PEM private keys | P-256, secp256k1, Ed25519 | P-256, secp256k1, Ed25519 | P-256, secp256k1, Ed25519 |
| AWS KMS signer | Yes (install `@aws-sdk/client-kms`) | No (use a custom signer) | Yes (`kms-aws` extra, Python 3.10 or later) |
| Azure Key Vault signer | Yes (install `@azure/keyvault-keys` and `@azure/identity`) | No (use a custom signer) | Yes (`kms-azure` extra) |
| HashiCorp Vault Transit signer | Yes | No (use a custom signer) | Yes (`kms-hashicorp` extra) |
| Custom signer | Yes | Yes | Yes |
| Intents with wait, approve, and reject helpers | Yes | Yes | Yes |
| Genesis builder | Yes | Yes | Yes |
| Automatic pagination | Yes | Yes | Yes |
| Response-signature verification (on by default) | Yes | Yes | Yes |
| Webhook channel management | No | Yes | No |
| Events listing | Yes | Yes | Yes |
| Command-line helper (`ripple-custody`) | Yes | No | Yes |
| Asynchronous API | Yes (all methods return promises) | No | Yes (`async` extra) |
| Example programs included in the package | Yes | No (available from Ripple) | Yes |
| Agent skill for AI coding assistants | Yes | Yes | Yes |


The following notes add detail to the table:

- **Custom signer.** Every SDK lets you supply your own signing function, so you can sign with any key store, including a hardware security module (HSM). The Java SDK has no built-in key management service (KMS) signers, and setting `kms_provider` in Java fails with an error. To use a KMS from Java, use a custom signer. For more information, see [Authentication and signing](/pt-br/products/custody/developer-experience/sdks/authentication-and-signing).
- **HashiCorp Vault.** The SDKs support only the Transit secrets engine. The TypeScript SDK authenticates to HashiCorp Vault with a token. The Python SDK uses a token or AppRole. Neither SDK renews the Vault token. For more information, see [HashiCorp Vault](/pt-br/products/custody/developer-experience/sdks/hashicorp-vault).
- **Webhooks.** Only the Java SDK manages webhook channels and verifies webhook payloads. In TypeScript and Python, use the REST API.
- **Events.** All three SDKs list the events in a domain. The TypeScript and Python SDKs can also paginate through them automatically. None of the SDKs subscribes to a push stream, so poll the list to pick up new events.
- **Retries.** The Java and synchronous Python clients use their HTTP transports' retry policies. The TypeScript SDK doesn't retry requests. No SDK replays a request after a `401` response. For defaults and configuration options, see [Errors and HTTP behavior](/pt-br/products/custody/developer-experience/sdks/errors-and-http#retries).
- **Virtual accounting.** No SDK supports omnibus virtual ledgers. Use the REST API.


## Examples

Each SDK has a set of runnable example programs. Most examples use the same number in every language. For example, `13` is the transfer-order example in TypeScript, Java, and Python. The following table lists the examples that cover the tasks in this documentation:

| Task | Example | Related documentation |
|  --- | --- | --- |
| Connect, and list domains | `00` Getting started | [Integrate via SDK](/pt-br/products/custody/get-started/integrate-via-sdk) |
| Page through results | `01` Listing and pagination | [Errors, pagination, and HTTP settings](/pt-br/products/custody/developer-experience/sdks/errors-and-http#pagination) |
| Create a user | `10` Create user | [Manage users and roles](/pt-br/products/custody/governance/users/manage-users-and-roles) |
| Create an account and add ledgers | `12` Account lifecycle | [Manage accounts with the API](/pt-br/products/custody/accounts-and-assets/accounts/manage-accounts-api) |
| Send assets | `13` Create transfer order, `14` Transfer and monitor | [Send assets](/pt-br/products/custody/transactions/send-and-receive/send-assets-api) |
| Estimate and set fees | `16` Fee management | [Send assets](/pt-br/products/custody/transactions/send-and-receive/send-assets-api) |
| Approve and reject intents | `20` Governance intents | [Manage intents and approvals](/pt-br/products/custody/governance/intents/manage-intents-and-approvals) |
| Migrate trusted keys | `22` Trusted keys migration | [Notary key rotation and migration](/pt-br/products/custody/operations-and-maintenance/security-maintenance/notary-key-rotation-and-migration) |
| Create a domain | `23` Create domain | [Manage domains](/pt-br/products/custody/governance/domains/manage-domains) |
| Release quarantined transfers | `32` Quarantine release agent | [Automatic quarantine release](/pt-br/products/custody/compliance/transaction-screening/automatic-quarantine-release-policy) |
| Validate and run genesis | `40` Genesis bootstrap | [Genesis payload reference](/pt-br/products/custody/governance/genesis/payload-reference) |


The examples also cover KMS signers, vault backups, XRP Ledger multi-purpose tokens (MPTs), and Ethereum contract calls. Some of these examples use different numbers in each language. To see the full set for your SDK, list the examples.

Use a test environment for examples
Examples that change state create real users, accounts, and transactions in the Ripple Custody instance that your configuration points to. Point your configuration at a test environment before you run them.

To get the examples, use the steps for your SDK:

TypeScript
The package includes the examples. List them, then copy the one you want and the shared `_bootstrap.ts` helper that most examples import. The `copy` command copies one file and doesn't overwrite an existing file:

```bash
npx ripple-custody examples list
npx ripple-custody examples copy 13_create_transfer_order.ts
npx ripple-custody examples copy _bootstrap.ts
```

If the example imports `./configuration_helper`, also copy that helper and install `dotenv`, which it depends on:

```bash
npx ripple-custody examples copy configuration_helper.ts
npm install dotenv
```

Run an example with your configuration file. Examples that change state run only when you set `ENABLE_WRITE=1`:

```bash
ENABLE_WRITE=1 npx tsx 13_create_transfer_order.ts --config ./config.toml
```

Java
The Java package doesn't include the examples. To get them, contact the [Ripple support team](/pt-br/products/custody/support/get-support).

Python
The package includes the examples as [marimo](https://marimo.io) notebooks. List them, then copy one by number:

```bash
ripple-custody examples list
ripple-custody examples copy 13
```

The `copy` command writes the notebooks to an `examples` folder and accepts a number, a group such as `1x`, or `all`. The folder includes a README that explains how to run the notebooks.

## Agent skills

Ripple maintains an agent skill for each SDK. A skill gives an AI coding assistant that supports agent skills, such as Claude Code, guidance on the SDK's API so that it can help you write integration code. Each skill covers configuration and authentication, intents and `PendingIntent`, pagination, error handling, response verification, transactions, compliance, genesis, and testing.

| SDK | Skill |
|  --- | --- |
| TypeScript | `ripple-custody-client-lib-typescript` |
| Java | `ripple-custody-client-lib-java` |
| Python | `ripple-custody-client-lib-python` |


The SDK packages don't include the skills. To get the skill for your SDK, contact the [Ripple support team](/pt-br/products/custody/support/get-support).

To use a skill with Claude Code, copy its folder into one of the following locations:

- `.claude/skills/` in your project, to make the skill available in that project.
- `~/.claude/skills/`, to make the skill available in all your projects.


Claude Code loads the skill when a task involves the SDK. Use the skill version that matches your SDK version, and review the code that the assistant writes before you run it.

To give an assistant access to this documentation as well, see [Connect AI assistants to the documentation](/pt-br/products/custody/developer-experience/connect-ai-assistants).

## SDK documentation

The following pages cover each part of the SDKs in detail:

- [Integrate via SDK](/pt-br/products/custody/get-started/integrate-via-sdk): install an SDK, configure it, and submit a first intent.
- [Configure the SDK](/pt-br/products/custody/developer-experience/sdks/configuration): configuration sources, every key and environment variable, and TLS settings.
- [Authentication and signing](/pt-br/products/custody/developer-experience/sdks/authentication-and-signing): signed-challenge and client-credentials authentication, key types, and KMS-backed and custom 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): submit intents, wait for them, and approve or reject them.
- [Response verification](/pt-br/products/custody/developer-experience/sdks/response-verification): how the SDKs verify API responses and how to supply the notary API public key.
- [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 to the new Java SDK.