Custody Integration

RebelFi integrates seamlessly with your existing custody infrastructure through an agent-based architecture. The custody agent runs alongside your custody solution and executes RebelFi operations while you maintain complete control over signing and funds.

Integration Overview

Choose Your Integration Pattern

Select the integration pattern that fits your custody setup

Deploy the Agent

Run the RebelFi agent alongside your custody infrastructure

Configure Authentication

Set up API keys and custody credentials

Start Polling

Agent begins polling for operations and executing them

Supported Custody Solutions

Agent Polling
Direct API Integration
Custom Integration

Works with any custody solution through agent-based polling.Two Options:

RebelFi Managed Agent: We run the agent with your custody credentials
Your Own Agent: You run a polling service that integrates with your custody

The agent polls RebelFi for pending transactions, signs them using your custody solution’s signing mechanism, and reports back execution status.Supported Providers:

Tatum KMS
- Fireblocks
- BitGo
Privy
- Custom/home-grown custody solutions

Best For: Maximum flexibility, any custody provider

Agent Architecture

How the Agent Works

┌─────────────────┐         Poll          ┌──────────────┐
│                 │◄─────────────────────►│              │
│  RebelFi API    │  Pending Transactions │    Agent     │
│                 │                        │              │
└─────────────────┘                        └──────┬───────┘
                                                  │
                                                  │ Sign & Submit
                                                  ▼
                                           ┌──────────────┐
                                           │   Custody    │
                                           │   Solution   │
                                           └──────┬───────┘
                                                  │
                                                  │ Broadcast
                                                  ▼
                                           ┌──────────────┐
                                           │  Blockchain  │
                                           └──────────────┘

Agent Responsibilities

Poll for Transactions: Check RebelFi API every 10-30 seconds for pending transactions
Lease Management: Claim transactions with a time-bound lease
Sign Transactions: Use custody solution’s signing mechanism to sign transaction payloads
Submit to Blockchain: Broadcast signed transactions to the blockchain network
Report Status: Update RebelFi with transaction hash and execution status
Error Handling: Retry logic for transient failures, report permanent errors

The agent pattern ensures you always maintain signing authority. Whether you run the agent yourself or use RebelFi’s managed agent, only your custody solution can sign transactions.

RebelFi Managed Agent vs. Your Own Agent

RebelFi Managed Agent
Your Own Agent

Simplest Option: RebelFi runs the agent infrastructure for you.

No deployment or maintenance required
RebelFi manages polling, retries, and error handling
You provide custody credentials securely
Monitor activity via dashboard
Automatic updates and scaling

Best for: Teams who want to focus on business logic, not infrastructure management

Integration Patterns by Provider

Pattern 1: Tatum KMS

Tatum KMS stores private keys and provides transaction signing via API. Installation:

npm install -g @rebelfi/agent

# Or Docker
docker pull rebelfi/agent:latest

Configuration (.env):

# RebelFi
REBELFI_BASE_URL=https://api.rebelfi.io
REBELFI_API_KEY=rfk_live_xxxxxxxxxxxxx

# Custody
CUSTODY_PROVIDER=tatum
TATUM_API_KEY=your_tatum_api_key

# Agent Settings
POLL_INTERVAL_MS=10000
LEASE_DURATION_MS=30000
LOG_LEVEL=info

Run the Agent:

rebelfi-agent start

# Or Docker
docker run -d \
  --env-file .env \
  --name rebelfi-agent \
  --restart unless-stopped \
  rebelfi/agent:latest

How It Works:

Agent polls /api/agent/transactions/poll
Receives unsigned transaction payload
Calls Tatum KMS to sign: POST https://api.tatum.io/v3/kms/{id}/sign
Submits signed transaction to blockchain
Reports transaction hash to RebelFi: POST /api/agent/transactions/{id}/report

Complete Tatum Integration Example

import { TatumSDK } from '@tatumio/tatum';
import axios from 'axios';

const tatumSDK = TatumSDK({ apiKey: process.env.TATUM_API_KEY });
const rebelfiAxios = axios.create({
  baseURL: process.env.REBELFI_BASE_URL,
  headers: { 'X-API-Key': process.env.REBELFI_API_KEY }
});

// Main agent loop
async function agentLoop() {
  while (true) {
    try {
      // Poll for pending transaction
      const { data } = await rebelfiAxios.post('/api/agent/transactions/poll', {
        leaseDurationMs: 30000
      });

      if (data.data.transaction) {
        const tx = data.data.transaction;

        // Sign with Tatum KMS
        const signedTx = await tatumSDK.kms.sign({
          signatureId: tx.signatureId,
          data: tx.unsignedTx
        });

        // Submit to blockchain
        const txHash = await blockchain.sendRawTransaction(signedTx);

        // Report back to RebelFi
        await rebelfiAxios.post(`/api/agent/transactions/${tx.id}/report`, {
          status: 'SUBMITTED',
          txHash: txHash
        });

        console.log(`Transaction ${tx.id} submitted: ${txHash}`);
      }
    } catch (error) {
      console.error('Agent error:', error);
    }

    // Wait before next poll
    await new Promise(resolve => setTimeout(resolve, 10000));
  }
}

agentLoop();

Pattern 2: Fireblocks (Agent Mode)

Use the RebelFi agent with Fireblocks’ signing infrastructure. Configuration (.env):

# RebelFi
REBELFI_BASE_URL=https://api.rebelfi.io
REBELFI_API_KEY=rfk_live_xxxxxxxxxxxxx

# Custody
CUSTODY_PROVIDER=fireblocks
FIREBLOCKS_API_KEY=your_fireblocks_api_key
FIREBLOCKS_SECRET_KEY_PATH=/path/to/fireblocks_secret.key
FIREBLOCKS_VAULT_ACCOUNT_ID=0

# Agent Settings
POLL_INTERVAL_MS=10000
LEASE_DURATION_MS=30000

Fireblocks-Specific Considerations:

Transaction Authorization Policy (TAP): Ensure your TAP allows RebelFi destination addresses
Whitelisting: Add RebelFi protocol addresses to your whitelist
Vault Accounts: Specify which vault account the agent should use
API Co-Signer: Configure if using Fireblocks’ API co-signer feature

For streamlined Fireblocks workflows, consider Direct API Integration where RebelFi submits transactions directly to Fireblocks using an API key.

Pattern 3: Privy

Privy provides embedded wallet infrastructure with custodial and non-custodial options. Configuration (.env):

# RebelFi
REBELFI_BASE_URL=https://api.rebelfi.io
REBELFI_API_KEY=rfk_live_xxxxxxxxxxxxx

# Custody
CUSTODY_PROVIDER=privy
PRIVY_APP_ID=your_privy_app_id
PRIVY_APP_SECRET=your_privy_app_secret

# Agent Settings
POLL_INTERVAL_MS=10000

Privy Integration:

Agent uses Privy’s server-side SDK to sign transactions
Works with both custodial wallets (Privy-managed keys) and delegated wallets
Supports Privy’s MFA and policy requirements

Pattern 4: Custom Custody

Build a custom adapter for your in-house or specialized custody solution. Requirements:

Transaction Signing: Ability to sign raw blockchain transactions
Programmatic Access: API or SDK for automated signing
Reliable Execution: Can handle polling loop (every 10-30 seconds)

Implementation Approach:

Extend Base Adapter

Create a custom adapter implementing the CustodyAdapter interface:

interface CustodyAdapter {
  sign(unsignedTx: string, metadata: any): Promise<string>;
  submit(signedTx: string, chain: string): Promise<string>;
  getAddress(walletId: string): Promise<string>;
}

Implement Signing Logic

class CustomCustodyAdapter implements CustodyAdapter {
  async sign(unsignedTx: string, metadata: any): Promise<string> {
    // Your custody solution's signing logic
    return await yourCustodySolution.sign({
      transaction: unsignedTx,
      walletId: metadata.walletId
    });
  }

  async submit(signedTx: string, chain: string): Promise<string> {
    // Submit to blockchain
    return await blockchain.sendTransaction(signedTx);
  }
}

Configure Agent

CUSTODY_PROVIDER=custom
CUSTOM_CUSTODY_ENDPOINT=https://your-custody-api.com
CUSTOM_CUSTODY_API_KEY=your_api_key

Test & Deploy

Test on devnet/testnet before production deployment

Request demo to discuss building custom adapters.

Agent Configuration Reference

Environment Variables

Variable	Required	Description
`REBELFI_BASE_URL`	Yes	RebelFi API URL (https://api.rebelfi.io)
`REBELFI_API_KEY`	Yes	Your RebelFi API key
`CUSTODY_PROVIDER`	Yes	Custody provider: `tatum`, `fireblocks`, `privy`, `custom`
`POLL_INTERVAL_MS`	No	Polling frequency (default: 10000ms)
`LEASE_DURATION_MS`	No	Transaction lease duration (default: 30000ms)
`LOG_LEVEL`	No	Logging level: `debug`, `info`, `warn`, `error` (default: `info`)
`MAX_RETRIES`	No	Max retry attempts for failed transactions (default: 3)

Provider-Specific Variables

Tatum:

TATUM_API_KEY - Tatum API key
TATUM_TESTNET - Use testnet (default: false)

Fireblocks:

FIREBLOCKS_API_KEY - Fireblocks API key
FIREBLOCKS_SECRET_KEY_PATH - Path to Fireblocks secret key file
FIREBLOCKS_VAULT_ACCOUNT_ID - Vault account ID

Privy:

PRIVY_APP_ID - Privy application ID
PRIVY_APP_SECRET - Privy application secret

Agent Deployment

Development

For local development and testing:

# Install
npm install -g @rebelfi/agent

# Configure
cat > .env <<EOF
REBELFI_BASE_URL=https://api.rebelfi.io
REBELFI_API_KEY=rfk_test_xxxxxxxxxxxxx
CUSTODY_PROVIDER=tatum
TATUM_API_KEY=your_test_api_key
TATUM_TESTNET=true
LOG_LEVEL=debug
EOF

# Run
rebelfi-agent start

Production

Option 1: Docker

# Create production .env file
cat > .env.prod <<EOF
REBELFI_BASE_URL=https://api.rebelfi.io
REBELFI_API_KEY=rfk_live_xxxxxxxxxxxxx
CUSTODY_PROVIDER=fireblocks
FIREBLOCKS_API_KEY=xxx
FIREBLOCKS_SECRET_KEY_PATH=/secrets/fireblocks.key
FIREBLOCKS_VAULT_ACCOUNT_ID=0
LOG_LEVEL=info
EOF

# Run with Docker
docker run -d \
  --name rebelfi-agent-prod \
  --env-file .env.prod \
  -v /path/to/secrets:/secrets:ro \
  --restart unless-stopped \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  rebelfi/agent:latest

Option 2: Systemd Service

# Create systemd service
sudo cat > /etc/systemd/system/rebelfi-agent.service <<EOF
[Unit]
Description=RebelFi Custody Agent
After=network.target

[Service]
Type=simple
User=rebelfi
WorkingDirectory=/opt/rebelfi-agent
EnvironmentFile=/opt/rebelfi-agent/.env.prod
ExecStart=/usr/bin/node /opt/rebelfi-agent/index.js
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable rebelfi-agent
sudo systemctl start rebelfi-agent

# Check status
sudo systemctl status rebelfi-agent

Option 3: Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rebelfi-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rebelfi-agent
  template:
    metadata:
      labels:
        app: rebelfi-agent
    spec:
      containers:
      - name: agent
        image: rebelfi/agent:latest
        envFrom:
        - secretRef:
            name: rebelfi-agent-secrets
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"

Monitoring & Operations

Health Checks

The agent exposes a health endpoint:

curl http://localhost:8080/health

# Response
{
  "status": "healthy",
  "lastPollAt": "2025-10-23T14:30:00Z",
  "lastExecutionAt": "2025-10-23T14:25:00Z",
  "pendingTransactions": 0
}

Logging

Agent logs include:

Poll attempts and responses
Transaction claims and leases
Signing operations
Blockchain submissions
Errors and retries

Log Format (JSON):

{
  "timestamp": "2025-10-23T14:30:00Z",
  "level": "info",
  "message": "Transaction executed",
  "transactionId": 123,
  "txHash": "0xabc...",
  "duration": 2500
}

Metrics

Key metrics to monitor:

Poll Frequency: Successful polls per minute
Transaction Throughput: Transactions executed per hour
Error Rate: Failed transactions / total attempts
Lease Expiry Rate: Transactions that expired before completion

Security Best Practices

API Key Management

Store API keys in secure secrets management (AWS Secrets Manager, HashiCorp Vault)
Rotate API keys periodically (recommended: every 90 days)
Use different API keys for dev/staging/production
Never log API keys in plain text

Network Security

Run agent in a private network segment
Restrict outbound traffic to only RebelFi API and blockchain RPC endpoints
Use TLS for all API communications
Consider using a VPN or private link for additional security

Custody Credentials

Store custody credentials (Fireblocks keys, etc.) encrypted at rest
Use hardware security modules (HSM) where possible
Implement least-privilege access for agent service accounts
Audit all signing operations

High Availability

Run agent with automatic restart (Docker --restart, systemd, K8s liveness probes)
Monitor agent health and alert on failures
Consider running multiple agents with lease-based coordination (built-in)
Implement dead letter queues for failed transactions

Troubleshooting

Agent not polling

Symptoms: No logs showing poll attemptsCheck:

Agent process is running
Network connectivity to api.rebelfi.io
API key is valid
Environment variables are loaded

Solution:

# Test API connectivity
curl https://api.rebelfi.io/api/agent/transactions/poll \
  -X POST \
  -H "X-API-Key: $REBELFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leaseDurationMs": 30000}'

Transactions not executing

Symptoms: Transactions appear in queue but never executeCheck:

Agent is successfully polling
Custody provider credentials are valid
Operation is not PENDING_APPROVAL (approve it first)
Agent has access to custody signing APIs

Solution: Check agent logs for signing errors. Test custody signing separately.

Lease expiry issues

Symptoms: Transactions repeatedly claimed but never completedCheck:

LEASE_DURATION_MS is sufficient for signing + submission
Network latency to custody provider
Custody provider response times

Solution: Increase LEASE_DURATION_MS to 60000ms (60 seconds) or higher for slow custody providers.

Next Steps

Quick Start

Deploy your first allocation

API Reference

Agent API documentation

Authentication

API key setup and security

Operations

Understanding operation lifecycle

Getting Started

Integration

Use Cases

Custody Integration

Integration Overview

Supported Custody Solutions

Agent Architecture

How the Agent Works

Agent Responsibilities

RebelFi Managed Agent vs. Your Own Agent

Integration Patterns by Provider

Pattern 1: Tatum KMS

Pattern 2: Fireblocks (Agent Mode)

Pattern 3: Privy

Pattern 4: Custom Custody

Agent Configuration Reference

Environment Variables

Provider-Specific Variables

Agent Deployment

Development

Production

Monitoring & Operations

Health Checks

Logging

Metrics

Security Best Practices

Troubleshooting

Next Steps

Quick Start

API Reference

Authentication

Operations

Getting Started

Integration

Use Cases

​Integration Overview

​Supported Custody Solutions

​Agent Architecture

​How the Agent Works

​Agent Responsibilities

​RebelFi Managed Agent vs. Your Own Agent

​Integration Patterns by Provider

​Pattern 1: Tatum KMS

​Pattern 2: Fireblocks (Agent Mode)

​Pattern 3: Privy

​Pattern 4: Custom Custody

​Agent Configuration Reference

​Environment Variables

​Provider-Specific Variables

​Agent Deployment

​Development

​Production

​Monitoring & Operations

​Health Checks

​Logging

​Metrics

​Security Best Practices

​Troubleshooting

​Next Steps

Quick Start

API Reference

Authentication

Operations

Integration Overview

Supported Custody Solutions

Agent Architecture

How the Agent Works

Agent Responsibilities

RebelFi Managed Agent vs. Your Own Agent

Integration Patterns by Provider

Pattern 1: Tatum KMS

Pattern 2: Fireblocks (Agent Mode)

Pattern 3: Privy

Pattern 4: Custom Custody

Agent Configuration Reference

Environment Variables

Provider-Specific Variables

Agent Deployment

Development

Production

Monitoring & Operations

Health Checks

Logging

Metrics

Security Best Practices

Troubleshooting

Next Steps