Fireblocks XRP SDK

A stateless SDK and REST API server for Fireblocks customers, simplifying advanced operations on the Ripple Ledger (XRPL).

---

⚡ Project Overview

Fireblocks XRP SDK enables secure, advanced XRP ledger operations via simple SDK calls or a stateless REST API.
Built for Fireblocks customers who want seamless DEX, token, and issuer operations on Ripple.

> Disclaimer
> This SDK relies on Fireblocks' RAW signing capabilities. Customers are fully responsible for safe usage, setup, and transaction outcomes. Fireblocks is not liable for any loss of funds resulting from the use of this code. Contact the Fireblocks Professional Services team for assistance.

$3

- Fireblocks workspace and API credentials (how to create an API key).
- RAW signing is enabled on your Fireblocks workspace. (Contact your Customer Success Manager for more information)
- TAP rules set to allow RAW transactions.
- Node.js v18+ for SDK usage.
- Docker (for REST API server).

---

🚀 Features

- Advanced XRPL support: DEX (OfferCreate/Cancel, Cross Currency Payments and Credentials), token & XRP transfers, setting trust lines, account settings>), clawback, freeze/unfreeze and burn.
- Fireblocks wallet integration: Secure MPC key management, raw signing flows, and transaction creation.
- Raw content validation with callback handler support Any Raw transaction created by the SDK includes the unhashed payload for further validation actions on your callback handler before signing.
- Stateless, pool-managed SDK: Efficient use of Fireblocks APIs with per-vault pooling.
- REST API: Simple to run as a Docker container.

---

📦 Installation

$3

Clone this repository and install dependencies:

``bash
git clone https://github.com/fireblocks/fireblocks-xrp-sdk.git
cd fireblocks-xrp-sdk
npm install
`

$3

Build and run the REST API server:

`bash
cp .env.example .env


Edit .env to your configuration


docker-compose up --build
`

- By default, the API server runs on port 3000.
- To change the port, set the PORT variable in your .env file.

> The project includes a sample docker-compose.yml and .env.example for quick setup.

---

⚙️ Configuration

All configuration is via environment variables.

Start by copying .env.example to .env and editing for your environment:

`bash
cp .env.example .env
`

| Variable Name | Required | Default | Purpose |
| ----------------------------- | :-----------------------------------------------: | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| FIREBLOCKS_API_KEY | Yes | – | Your Fireblocks API key UUID |
| FIREBLOCKS_SECRET_KEY | No (for direct use in the SDK) / Yes (for Docker) | – | Fireblocks private key to be used in the SDK or Docker |
| FIREBLOCKS_VAULT_ACCOUNT_ID | No | – | Optional - Can be added to use a single wallet SDK intance, should be ommited when used as a dockerized server. |
| FIREBLOCKS_ASSET_ID | No | XRP_TEST | Use XRP for mainnet, XRP_TEST for testnet |
| FIREBLOCKS_BASE_PATH | No | US | Fireblocks API environment (see docs for region URLs) |
| SDK_LOG_LEVEL | No | info | Log level: debug, info, warn, error, fatal |
| PORT | No | 3000 | API server port (REST mode) |

---

🔑 Mounting Your Fireblocks Private Key in Docker

The SDK and REST API require access to your Fireblocks API private key (FIREBLOCKS_SECRET_KEY) for signing and secure communication with Fireblocks.
When running inside Docker, you must mount this file and reference it correctly.

1. Store Your Private Key
Place your Fireblocks API private key file in the project directory under ./secrets/fireblocks_secret.key:

`bash
your-project-root/
│
├─ .env
├─ docker-compose.yml
└─ ...
`

#### Important: Never commit your .env to source control.

2. Reference the Private Key in .env
Set the environment variable in your .env file to match the path inside the container:

`bash
FIREBLOCKS_SECRET_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n... more base64 ...\n-----END PRIVATE KEY-----"
`

3. How Docker Compose Mounts the Key
Your docker-compose.yml already mounts the .env file into the container:

`yaml
services:
fireblocks-xrp-sdk:
build:
context: .
dockerfile: Dockerfile
volumes:
- ./.env:/app/.env:ro
ports:
- "3000:3000"
env_file: ./.env
environment:
- FIREBLOCKS_SECRET_KEY=-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n... more base64 ...\n-----END PRIVATE KEY-----
restart: unless-stopped
`

This setup ensures that:

The .env file with your Fireblocks credentials is available at /app/.env.

The FIREBLOCKS_SECRET_KEY environment variable allows the SDK to use the key to create a Fireblocks instance.

4. Running the API Server
Build and run the container with:

`bash
docker-compose up --build
`

5. Security Notes
Do not include your private key in the repo.
Only give read permissions (:ro) to the mounted secret.
Consider using secrets management solutions for production deployments.

🛠️ Usage

$3

Sample usage via direct SDK in Node.js (see /examples for more):

`ts
import { readFileSync } from "fs";
import { FbksXrpApiService } from "./src/api/ApiService";
import { TransactionType } from "./src/pool/types";
import { BasePath } from "@fireblocks/ts-sdk";
import dotenv from "dotenv";

dotenv.config();

(async () => {
const FIREBLOCKS_API_SECRET_PATH = "./fireblocks_secret.key";

const apiSecret =
readFileSync(FIREBLOCKS_API_SECRET_PATH, "utf8") ||
process.env.FIREBLOCKS_SECRET_KEY?.replace(/\\n/g, "\n");

const apiService = new FbksXrpApiService({
apiKey: process.env.FIREBLOCKS_API_KEY || "",
apiSecret,
assetId: process.env.FIREBLOCKS_ASSET_ID || "XRP_TEST",
basePath: (process.env.FIREBLOCKS_BASE_PATH as BasePath) || BasePath.US,
});

const params = {
sellAmount: "10",
buyAmount: {
currency: "THT",
issuer: "rpbkpPF8PrPuMN8NgEVkCsJDCWwP9KePFq",
value: "2",
},
flags: {
tfPassiveOffer: true,
tfSellOffer: true,
},
domainId:
"ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890",
};

const opts: ExecuteTransactionOpts = {
vaultAccountId: process.env.FIREBLOCKS_VAULT_ACCOUNT_ID || "",
transactionType: TransactionType.OFFER_CREATE,
params,
};

const res = await apiService.executeTransaction(opts);

if ("result" in res) {
console.log(Tx submitted: ${res.result.hash});
} else {
console.log(Transaction submitted with ID: ${res.id});
}

await apiService.shutdown();
})();
`

> See more SDK samples in /examples/.

$3

Any transaction created by the SDK (excluding xrpTransfer() that does not rely on Raw signing) includes the unhased transaction payload as an additional extraParameters key (unhashedTxPayload), this is passed to allow pre-signature validation by a callback handler instance connected to your Fireblocks API Co-Signer instance.

In the transaction object received by the callback handler, the extraParameters object will have this structure:

`json
{
"rawMessageData": {
"messages": [
{
"content": "4147FCCCB874E67DDB05C3D353972EFA21DC0D18F6F0B3768C22AFDAAEEC10E7"
}
]
},
"unhashedTxPayload": {
"Fee": "10",
"Amount": {
"value": "100",
"issuer": "rhsMZjNb4ehEHdfLbMCRBnwMr7XAnicnVS",
"currency": "FBX"
},
"Account": "rpbkpPF8PrPuMN8NgEVkCsJDCWwP9KePFq",
"Sequence": 7855319,
"Destination": "rfSeUdwJC4ejRZ3mNfdH7KMWPyGGx6UTmf",
"SigningPubKey": "03077CBD3FC5F7B9FC8364C83900A78659AF60D16C62DB2860C498C3593D29BA2D",
"TransactionType": "Payment",
"LastLedgerSequence": 8224033
}
}
`

Use the unhashedTxPayload parameter to validate the raw message (content) before signing it.

$3

#### 1. Run API Server

`bash
docker-compose up --build
`

#### 2. API Authentication

All requests require valid Fireblocks API credentials via environment parameters.
No additional API key/JWT is needed on REST endpoints.

#### 3. Try Endpoints (cURL)

OfferCreate example:

`bash
curl -X POST http://localhost:3000/api/dex/offerCreate/ \
-H "Content-Type: application/json" \
-d '{
"sellAmount": "10",
"buyAmount": {
"currency": "THT",
"issuer": "rpbkpPF8PrPuMN8NgEVkCsJDCWwP9KePFq",
"value": "2"
},
"flags": {
"tfPassiveOffer": true,
"tfSellOffer": true
},
"domainId":
"ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890",
}'
`

#### 4. Postman Collection

Import Fireblocks-XRP-SDK-API.postman_collection.json
_All REST API routes and sample payloads are included for testing._

$3

`json
{
"api_version": 2,
"id": 28,
"result": {
"close_time_iso": "2025-06-18T18:32:21Z",
"ctid": "C07D2C9900000001",
"hash": "4B2FA0715A4DBBBBC64AEDB456EB66C5EB51622563E9844301221379BEE0A0B2",
"ledger_hash": "A9694DDCED235E2DCB12A83EF6635DD3ED6D3C6453382667684D8129A5C6E436",
"ledger_index": 8203417,
"meta": {
"AffectedNodes": [
{
"CreatedNode": {
"LedgerEntryType": "Offer",
"LedgerIndex": "99DABC072D601478026701338BC2B949EF8496E9EBEC2178CFFADC4E8DAB11C3",
"NewFields": {
"Account": "rNZxC1fL1qREWqu9N5A74nHWwqo39XoNYB",
"BookDirectory": "C0E0F7D521A20EE39BA81685BF4169312FF9FB83CFFB999D54071AFD498D0000",
"Flags": 196608,
"Sequence": 7855642,
"TakerGets": "10",
"TakerPays": {
"currency": "THT",
"issuer": "rpbkpPF8PrPuMN8NgEVkCsJDCWwP9KePFq",
"value": "2"
}
}
}
},
{
"ModifiedNode": {
"FinalFields": {
"Flags": 0,
"Owner": "rNZxC1fL1qREWqu9N5A74nHWwqo39XoNYB",
"RootIndex": "AAEC4ADFADE1BF6FB00855A846C68D52268D942F4E25EC2A87BDE6815A4FED0A"
},
"LedgerEntryType": "DirectoryNode",
"LedgerIndex": "AAEC4ADFADE1BF6FB00855A846C68D52268D942F4E25EC2A87BDE6815A4FED0A",
"PreviousTxnID": "F6B1A95D26D57322EC872B2C3D65518DC47430218827C3F0349388F963E27CCB",
"PreviousTxnLgrSeq": 8167686
}
},
{
"ModifiedNode": {
"FinalFields": {
"ExchangeRate": "54071afd498d0000",
"Flags": 0,
"RootIndex": "C0E0F7D521A20EE39BA81685BF4169312FF9FB83CFFB999D54071AFD498D0000",
"TakerGetsCurrency": "0000000000000000000000000000000000000000",
"TakerGetsIssuer": "0000000000000000000000000000000000000000",
"TakerPaysCurrency": "0000000000000000000000005448540000000000",
"TakerPaysIssuer": "118A2EE1CD3C489E36DDD301C7E702DC0D8DF53F"
},
"LedgerEntryType": "DirectoryNode",
"LedgerIndex": "C0E0F7D521A20EE39BA81685BF4169312FF9FB83CFFB999D54071AFD498D0000",
"PreviousTxnID": "F6B1A95D26D57322EC872B2C3D65518DC47430218827C3F0349388F963E27CCB",
"PreviousTxnLgrSeq": 8167686
}
},
{
"ModifiedNode": {
"FinalFields": {
"Account": "rNZxC1fL1qREWqu9N5A74nHWwqo39XoNYB",
"Balance": "40999850",
"Flags": 0,
"OwnerCount": 4,
"Sequence": 7855643
},
"LedgerEntryType": "AccountRoot",
"LedgerIndex": "E3D4BE3CCB2AF535B829037621B57F5B3914AC4ECED4B65D407386FB4938199B",
"PreviousFields": {
"Balance": "40999860",
"OwnerCount": 3,
"Sequence": 7855642
},
"PreviousTxnID": "7660C7BF2BDA0CC2EC15AFA3CDC5ECCBB7676AB20655D927C743FA4E8408E00F",
"PreviousTxnLgrSeq": 8203373
}
}
],
"TransactionIndex": 0,
"TransactionResult": "tesSUCCESS"
},
"tx_json": {
"Account": "rNZxC1fL1qREWqu9N5A74nHWwqo39XoNYB",
"Fee": "10",
"Flags": 589824,
"LastLedgerSequence": 8203434,
"Sequence": 7855642,
"SigningPubKey": "031CD7DD2D580A62D45F2A180F04F39DC9222570A23E0F092E1D7C49E68B731FB4",
"TakerGets": "10",
"TakerPays": {
"currency": "THT",
"issuer": "rpbkpPF8PrPuMN8NgEVkCsJDCWwP9KePFq",
"value": "2"
},
"TransactionType": "OfferCreate",
"TxnSignature": "3045022100FD948DE8CC15EE77F6DB1FF47BD27B93422CE65CEDD320B82E7B06BAE253AA21022001B12BAC6ACBB65B8A6FDEF6E7E665128DD0BD98ED37463F9E41C1B659F27613",
"date": 803586741,
"ledger_index": 8203417
},
"validated": true
},
"type": "response"
}
`

---

📚 API & Documentation Endpoints

The running API server exposes interactive documentation and SDK reference for easier integration and onboarding:

| Purpose | URL | Description |
| --------------------- | --------------------------------- | --------------------------------------------------------- |
| Swagger UI | http://localhost:3000/api-docs | Interactive REST API explorer for all endpoints. |
| TypeDoc Reference | http://localhost:3000/type-docs | SDK Classes/Methods documentation (generated by TypeDoc). |

> Both URLs assume the default port 3000—change if you modify your server port.
> The TypeDoc reference is also available here.

DEX Routes:

- POST /api/dex/offerCreate/:vaultAccountId
- POST /api/dex/offerCancel/:vaultAccountId
- POST /api/dex/crossCurrencyPayment/:vaultAccountId
- POST /api/dex/credentialCreate/:vaultAccountId
- POST /api/dex/credentialAccept/:vaultAccountId
- POST /api/dex/credentialDelete/:vaultAccountId

Token Routes:

- POST /api/token/tokenTransfer/:vaultAccountId
- POST /api/token/accountSet/:vaultAccountId
- POST /api/token/burnToken/:vaultAccountId
- POST /api/token/clawback/:vaultAccountId
- POST /api/token/freezeToken/:vaultAccountId
- POST /api/token/trustSet/:vaultAccountId
- POST /api/token/xrpTransfer/:vaultAccountId

Each endpoint expects a JSON body and returns a transaction result.
_See Postman or /examples/ for detailed payloads._

$3

All errors return a JSON.

Bad request example (400):

`json
{
"error": "Missing vault account ID",
"message": "Vault account Id is missing from the request URL"
}
`

Not found example (404):

`json
{
"error": "Not Found",
"message": "Cannot POST /api/dex/offerCanc"
}
`

---

🧪 Development & Contribution

- Run tests:

`bash
npm run test
``

- CI/CD:
The project uses GitHub Actions for lint, build, and tests.
- Contributions:
PRs and issues are welcome!

---

🛡️ Security & Responsibility

> RAW signing is a powerful operation.
> Ensure your Fireblocks workspace is properly configured.
> Fireblocks is not responsible for loss of funds caused by incorrect use of this SDK or API.

---

📝 License

MIT License

---

💬 Support

For setup help, troubleshooting, or feature requests, please contact the Fireblocks Professional Services team.

---