# Process cold vault operations with the API

Use this page for programmatic cold vault operations. For the conceptual model, see [Cold vaults](/products/custody/identity-and-access/vault-management/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.


## API endpoints

| Operation | System | Endpoint |
|  --- | --- | --- |
| Export pending operations | Online API | [Export prepared operations](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1{vaultid}~1operations~1prepared/get) |
| Import signed operations | Online API | [Import signed operations](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1operations~1signed/post) |
| Get vault details | Online API | [Get vault details](/products/custody/reference/api/openapi/vaults/getvault) |
| Upload operations | Cold bridge | `POST {ColdBridgeURL}/v1/feed/upload` |
| Check signing status | Cold bridge | `GET {ColdBridgeURL}/v1/feed/status` |
| Download signed operations | Cold bridge | `GET {ColdBridgeURL}/v1/feed/download` |
| Decode payload | Cold bridge | `POST {ColdBridgeURL}/v1/feed/decode` |


## Complete the first-time vault handshake

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:

```sh
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](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1operations~1signed/post):

```sh
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`:

```sh
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.

## Process accounts, transactions, or 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.

### Step 1: Export pending operations

Call [Export prepared operations](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1{vaultid}~1operations~1prepared/get):


```sh
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.

### Step 2: Decode and verify the payload

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


```sh
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.

Verify before signing
Cold vault signing is a high-control operation. Decode and review the payload before signing, especially for transactions. Once a signed transaction is broadcast to the blockchain network, it cannot be recalled by Ripple Custody.

### Step 3: Upload operations to the cold bridge

Upload the exported file to the cold bridge:


```sh
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.

### Step 4: Check signing status

Call the cold bridge status endpoint:


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

The response includes counters for unsigned and signed operations:


```json
{
  "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.

### Step 5: Download signed operations

Download the signed payload from the cold bridge:


```sh
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.

### Step 6: Import signed operations

Import the signed payload into Ripple Custody with [Import signed operations](/products/custody/reference/api/openapi/vaults/paths/~1v1~1vaults~1operations~1signed/post):


```sh
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.

## Related topics

- [Process cold vault operations in the UI](/products/custody/identity-and-access/vault-management/cold-vault-setup-ui)
- [Cold vaults](/products/custody/identity-and-access/vault-management/cold-vaults)
- [Deploy a cold bridge](/products/custody/deployment/install/cold-bridge-deployment)
- [Recover a cold vault](/products/custody/identity-and-access/vault-management/cold-vault-recovery)