Process cold vault operations with the API

Use this page for programmatic cold vault operations. For the conceptual model, see Cold vaults.

Cold vault workflows involve two systems:

• The online Ripple Custody API, which requires JWT authentication.
• The cold bridge API, which runs on the air-gapped workstation and provides local endpoints for upload, status, download, and payload inspection.

When you register a new cold vault, it can be created in a Pending state because the cold vault cannot automatically connect to the online deployment. Complete the handshake by downloading the vault payload from the cold bridge and importing it into Ripple Custody.

1. On the air-gapped workstation, download the vault payload from the cold bridge:

   curl -X GET "{ColdBridgeURL}/v1/feed/download?clean=false" \
     --output cold-vault-handshake.dat

   Use clean=false until the payload is successfully imported. After confirming successful import, you can use clean=true to clear the cold bridge cache.

2. Transfer cold-vault-handshake.dat to the online environment using your approved transfer process.

3. Import the payload into Ripple Custody with Import signed operations:

   curl -X POST "${CUSTODY_API_URL}/v1/vaults/operations/signed" \
     -H "Authorization: Bearer ${JWT_TOKEN}" \
     -F "files=@cold-vault-handshake.dat"

4. Verify that the vault status is Completed:

   curl -X GET "${CUSTODY_API_URL}/v1/vaults/${VAULT_ID}" \
     -H "Authorization: Bearer ${JWT_TOKEN}"

After the vault status is Completed, you can use the vault for account creation, transactions, and manifests.

Any accounts, transactions, or manifests created for a cold vault remain Pending until the cold vault signs the prepared operations. You can batch multiple pending operations into the same export.

Call Export prepared operations:

curl -X GET "${CUSTODY_API_URL}/v1/vaults/${VAULT_ID}/operations/prepared" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  --output cold-vault-operations.dat

Transfer cold-vault-operations.dat to the air-gapped workstation using your approved transfer process.

Use the cold bridge decode endpoint to inspect the exported payload before signing:

curl -X POST "{ColdBridgeURL}/v1/feed/decode" \
  -F "files=@cold-vault-operations.dat"

For transactions, verify the destination address, amount, network, and fees before allowing the cold vault to sign.

Upload the exported file to the cold bridge:

curl -X POST "{ColdBridgeURL}/v1/feed/upload" \
  -F "files=@cold-vault-operations.dat"

After upload, the vault processes the data from the cold bridge and signs the pending operations.

Call the cold bridge status endpoint:

curl -X GET "{ColdBridgeURL}/v1/feed/status"

The response includes counters for unsigned and signed operations:

{
  "accountToSign": 0,
  "accountSigned": 0,
  "transactionToSign": 0,
  "transactionSigned": 0,
  "manifestToSign": 0,
  "manifestSigned": 0
}

When the ToSign counters are zero, all pending operations in the uploaded payload have been signed.

Download the signed payload from the cold bridge:

curl -X GET "{ColdBridgeURL}/v1/feed/download?clean=false" \
  --output signed-cold-vault-operations.dat

Transfer signed-cold-vault-operations.dat back to the online environment.

Import the signed payload into Ripple Custody with Import signed operations:

curl -X POST "${CUSTODY_API_URL}/v1/vaults/operations/signed" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -F "files=@signed-cold-vault-operations.dat"

After import, Ripple Custody continues processing the account, transaction, or manifest.

• Process cold vault operations in the UI
• Cold vaults
• Deploy a cold bridge
• Recover a cold vault