Quickstart

This guide walks you through the essential steps to start using the Carabaas API — from authentication to creating your first transaction.

Environments

Environment	Console	API Base URL
Sandbox	sandbox.carabaas.com	https://api-sandbox.carabaas.com/api/v1
Production	console.carabaas.com	https://api.carabaas.com/api/v1

tip

Start in sandbox. Every feature works end-to-end on testnet — build and test your full integration before going live, no real funds involved.

Prerequisites

• A Carabaas account (request access)
• An RSA key pair for API authentication
• curl or any HTTP client

Step 1: Generate RSA Keys

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

Step 2: Create an API Client

Create an API client in the Console (Organization → API tab → Add API Client). You'll receive a Client ID. Then attach your public key to the client.

Step 3: Create a Self-Signed JWT

All API requests use JWT tokens in the Authorization: Bearer header.

const jwt = require('jsonwebtoken');
const fs = require('fs');
const { createHash, createPublicKey } = require('crypto');

const privateKey = fs.readFileSync('private_key.pem');
const pubKeyObject = createPublicKey({ key: privateKey, format: 'pem' });
const publicKey = pubKeyObject.export({ format: 'pem', type: 'spki' });
const keyHash = deriveKeyHash(publicKey);

const clientId = 'f7hJ9kL1mN3pQ5rS7tUvWx';

const payload = {
  sub: keyHash,
  iss: clientId,
  exp: Math.floor(Date.now() / 1000) + 3600, // expires in 1 hour
};

const token = jwt.sign(payload, privateKey, {
  header: { typ: 'JWT', alg: 'RS256', kid: keyHash },
});

function deriveKeyHash(publicKey) {
  const cleanKey = publicKey
    .replace('-----BEGIN PUBLIC KEY-----', '')
    .replace('-----END PUBLIC KEY-----', '')
    .replace(/\n/g, '');
  return createHash('sha256')
    .update(Buffer.from(cleanKey, 'base64'))
    .digest('hex');
}

console.log(token);

Step 4: Verify Authentication

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     https://api.carabaas.com/api/v1/profile

You should receive your client profile information.

Step 5: List Your Vaults

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     "https://api.carabaas.com/api/v1/vaults?organizationId=djk2wDuMhsx9KR2r7JgBQW"

Step 6: Create an Address

curl -X POST \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "eFjwUQXB8CMnrTHSgYzaL6",
       "network": "ethereum-sepolia",
       "name": "My First Address"
     }' \
     https://api.carabaas.com/api/v1/addresses

Step 7: Create a Transaction

curl -X POST \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "orderId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
       "vaultId": "kR7mNpX2wQvL9sYhBjD4eT",
       "addressId": "gMP71sR5sNUnGdKFTsNzp6",
       "destination": "0x742d35Cc6634C0532925a3b8...",
       "network": "ethereum-sepolia",
       "asset": "c1",
       "amount": "0.01",
       "feePriority": "medium"
     }' \
     https://api.carabaas.com/api/v1/transactions

What's Next?

Topic	Description
Authentication	JWT details, key rotation, token security
Vaults	Create and manage vault structures
Transactions	Full transaction lifecycle
Approval Workflow	Set up quorum-based approvals
Webhooks	Real-time event notifications
Go-Live Checklist	Prepare for production