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.
- 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.
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.
| 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. For installation steps, see Integrate via SDK.
| 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_providerin Java fails with an error. To use a KMS from Java, use a custom signer. For more information, see 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.
- 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
401response. For defaults and configuration options, see Errors and HTTP behavior. - Virtual accounting. No SDK supports omnibus virtual ledgers. Use the REST API.
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 |
| Page through results | 01 Listing and pagination | Errors, pagination, and HTTP settings |
| Create a user | 10 Create user | Manage users and roles |
| Create an account and add ledgers | 12 Account lifecycle | Manage accounts with the API |
| Send assets | 13 Create transfer order, 14 Transfer and monitor | Send assets |
| Estimate and set fees | 16 Fee management | Send assets |
| Approve and reject intents | 20 Governance intents | Manage intents and approvals |
| Migrate trusted keys | 22 Trusted keys migration | Notary key rotation and migration |
| Create a domain | 23 Create domain | Manage domains |
| Release quarantined transfers | 32 Quarantine release agent | Automatic quarantine release |
| Validate and run genesis | 40 Genesis bootstrap | 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.
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:
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:
npx ripple-custody examples list
npx ripple-custody examples copy 13_create_transfer_order.ts
npx ripple-custody examples copy _bootstrap.tsIf the example imports ./configuration_helper, also copy that helper and install dotenv, which it depends on:
npx ripple-custody examples copy configuration_helper.ts
npm install dotenvRun an example with your configuration file. Examples that change state run only when you set ENABLE_WRITE=1:
ENABLE_WRITE=1 npx tsx 13_create_transfer_order.ts --config ./config.tomlRipple 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.
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.
The following pages cover each part of the SDKs in detail:
- Integrate via SDK: install an SDK, configure it, and submit a first intent.
- Configure the SDK: configuration sources, every key and environment variable, and TLS settings.
- Authentication and signing: signed-challenge and client-credentials authentication, key types, and KMS-backed and custom signers.
- HashiCorp Vault: sign with a Vault Transit key.
- Work with intents: submit intents, wait for them, and approve or reject them.
- Response verification: how the SDKs verify API responses and how to supply the notary API public key.
- Errors and HTTP behavior: exception types, timeouts, and retries.
- Migrate from the legacy Java SDK: move from the
com.metacoSDK to the new Java SDK.