# Process cold vault operations with the API

Use this page for programmatic cold vault operations. For the conceptual model, see [Cold vaults](/products/custody/v1.37/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 cold vault server 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/v1.37/reference/api/openapi/vaults/paths/~1v1~1vaults~1{vaultid}~1operations~1prepared/get) |
| Import signed operations | Online API | [Import signed operations](/products/custody/v1.37/reference/api/openapi/vaults/paths/~1v1~1vaults~1operations~1signed/post) |
| Get vault details | Online API | [Get vault details](/products/custody/v1.37/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 start 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 cold vault server, download the vault payload from the cold bridge:

```sh
curl -X GET "{ColdBridgeURL}/v1/feed/download?clean=false" \
  --output cold-vault-handshake.dat
```
The `clean` parameter is optional. `clean=true` clears the cold bridge cache after the download, and `clean=false` keeps the payload available so you can download it again if the import fails. The cold bridge UI always downloads with `clean=true`.
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/v1.37/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

Accounts and manifests created for a cold vault remain `Pending`, and transaction orders remain `Prepared`, until the cold vault signs the exported operations. You can batch multiple unsigned operations into the same export.

### Step 1: Export pending operations

Call [Export prepared operations](/products/custody/v1.37/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 cold vault server using your approved transfer process.

### Step 2: Decode and verify the payload (optional)

Decoding is optional, but recommended for transactions. 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. After a signed transaction broadcasts to the blockchain network, Ripple Custody cannot recall it.

### 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, the vault has signed all operations in the uploaded payload.

### 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/v1.37/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/v1.37/identity-and-access/vault-management/cold-vault-setup-ui)
- [Cold vaults](/products/custody/v1.37/identity-and-access/vault-management/cold-vaults)
- [Deploy a cold bridge](/products/custody/v1.37/deployment/install/cold-bridge-deployment)
- [Recover a cold vault](/products/custody/v1.37/identity-and-access/vault-management/cold-vault-recovery)