Glossary

This glossary defines core concepts used throughout RebelFi’s platform and APIs.

Wallets & Accounts

Organization (Org)

Your company or entity within RebelFi. All wallets, operations, and allocations belong to an organization. API Field: organizationId, organization Example: “Acoriana Corp”, “Treasury DAO”

Org Wallet (Organization Wallet)

A wallet address you own, imported into RebelFi for monitoring. Key Points:

You control the private keys (custody)
RebelFi monitors the address
Can be used for yield optimization

API Field: orgWalletId, orgWallet Example:

{
  "id": 123,
  "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "chainName": "SOLANA",
  "name": "Treasury Wallet"
}

Operational Wallet (OpWallet)

An Org Wallet that is actively monitored for yield optimization opportunities. Also Known As:

Managed Wallet (in some docs)
Monitored Wallet (in API endpoints like /wallets/monitored)
OpWallet (in code and API responses like opWalletId)

These all refer to the same thing: A wallet monitored for yield. Configuration:

Buffer Amount: Minimum liquidity to maintain
Enable Yield: Whether to optimize for yield

API Fields: opWalletId, managedWalletId (interchangeable) Example:

{
  "id": 456,              // opWalletId or managedWalletId
  "orgWalletId": 123,
  "enableYield": true,
  "bufferAmountBase": "100000"
}

Terminology Note: Throughout this documentation, we primarily use “Operational Wallet” or “OpWallet”. If you see opWalletId or managedWalletId in API responses, they’re the same thing.

Financial Concepts

Buffer Amount

Minimum liquidity to keep available (not deployed to yield) in an operational wallet. Purpose:

Ensure funds available for immediate withdrawals
Maintain operational liquidity

Behavior:

Funds above buffer → eligible for yield deployment
Funds at or below buffer → kept liquid

Format: Base units (e.g., "100000" = 0.1 USDC for 6 decimals) Example:

Buffer: 0.1 USDC
Total balance: 1.0 USDC
Eligible for yield: 0.9 USDC

Position

A snapshot view of wallet balances for a specific token. Components:

Total: All funds (available + reserved + allocated)
Available: Liquid, ready for operations
Reserved: Locked by active operations
Allocated: Deployed to yield protocols
Principal: Original funds (total - yield earned)
Yield: Cumulative yield earned

Formula: Total = Available + Reserved + Allocated API Endpoint (Planned): GET /api/token-positions/op-wallet/:id Example:

{
  "balances": {
    "total": { "amount": "10.50", "currency": "USDC" },
    "available": { "amount": "5.00", "currency": "USDC" },
    "reserved": { "amount": "2.00", "currency": "USDC" },
    "allocated": { "amount": "3.50", "currency": "USDC" },
    "principal": { "amount": "10.00", "currency": "USDC" },
    "yield": { "amount": "0.50", "currency": "USDC" }
  }
}

Reservation

A temporary financial lock on available funds during an operation. Lifecycle:

Created: When operation enters PLANNED status
Active: Locks funds (reduces available balance)
Consumed: When operation completes successfully
Released: When operation fails or is rejected

Purpose: Prevents double-spending while operation is executing Status Values:

ACTIVE - Currently locking funds
CONSUMED - Operation completed, lock removed
RELEASED - Operation failed/rejected, funds returned

Example Flow:

Initial: 10 USDC available

Operation created (SUPPLY 5 USDC):
  → Reservation: 5 USDC (ACTIVE)
  → Available: 5 USDC (10 - 5)
  → Reserved: 5 USDC

Operation completes:
  → Reservation: 5 USDC (CONSUMED)
  → Available: 5 USDC
  → Reserved: 0 USDC
  → Allocated: 5 USDC (new allocation created)

Allocation

Funds actively deployed to a yield protocol, earning yield. Lifecycle:

Created: When SUPPLY operation completes
Active: Earning yield
Unwinding: Being withdrawn
Closed: Fully withdrawn

Status Values:

ACTIVE - Earning yield
UNWINDING - Withdrawal in progress
CLOSED - No longer active

Components:

Principal: Original amount deployed
Yield: Cumulative yield earned
Current Value: Principal + Yield
APY: Current annual percentage yield

API Endpoint: GET /api/v1/allocations Example:

{
  "id": 789,
  "balances": {
    "allocated": { "amount": "5.00", "currency": "USDC" },
    "principal": { "amount": "4.95", "currency": "USDC" },
    "yield": { "amount": "0.05", "currency": "USDC" }
  },
  "performance": {
    "currentApy": "6.0",
    "lifetimeYield": { "amount": "0.05", "currency": "USDC" }
  },
  "status": "ACTIVE"
}

Operations

Operation

A structured workflow representing business intent (deploy funds, withdraw funds, transfer). Types:

SUPPLY - Deploy funds to yield protocols
DISBURSE - Withdraw funds from yield
TRANSFER - Move funds between wallets

Status Values:

PLANNED - Created, funds reserved
PENDING_APPROVAL - Awaiting manual approval
EXECUTING - Being signed by custody
COMPLETED - Successfully executed
FAILED - Execution failed
REJECTED - Manually rejected
ABORTED - System aborted

Lifecycle:

PLANNED → PENDING_APPROVAL → EXECUTING → COMPLETED
                ↓                ↓
            REJECTED          FAILED

API Endpoint: GET /api/core/operations/queue, GET /api/core/operations/history

Operation Step

An individual action within an operation (e.g., UNWIND, TRANSFER). Common Steps:

SUPPLY_TO_PROVIDER - Deploy to yield protocol
UNWIND_FROM_PROVIDER - Withdraw from yield protocol
TRANSFER_OUT - Send to external address

Status: Same as operation (PENDING, EXECUTING, COMPLETED, FAILED) Example (Disburse Operation):

{
  "id": 790,
  "type": "DISBURSE",
  "steps": [
    {
      "type": "UNWIND_FROM_PROVIDER",
      "status": "EXECUTING",
      "amount": "2.00",
      "provider": "Drift Protocol"
    },
    {
      "type": "TRANSFER_OUT",
      "status": "PENDING",
      "amount": "2.00",
      "destination": "ExternalWalletAddress..."
    }
  ]
}

Transaction Attempt

A blockchain transaction executing one or more operation steps. Lifecycle:

Created: Unsigned transaction generated
Claimed: Agent claimed via polling
Submitted: Signed and submitted to blockchain
Confirmed: Blockchain confirmation received

Components:

Unsigned TX: Transaction payload for signing
Lease: Time-bound claim by agent
TX Hash: Blockchain transaction ID (after submission)

API Endpoint: POST /api/agent/transactions/poll Example:

{
  "id": 5001,
  "attemptId": 5001,
  "operationId": 789,
  "unsignedTx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAHEAoMCg...",
  "status": "SUBMITTED",
  "txHash": "5aApzp1XxiNzFotAiZt6z7BaTTYCS7964ycpxwYp4eVy...",
  "leaseExpiresAt": "2025-01-30T14:01:30Z"
}

Blockchain & Transactions

Chain Transaction

An immutable blockchain fact - what actually happened on-chain. Components:

TX Hash: Blockchain transaction ID
Block Number: Block containing transaction
Confirmations: Number of confirmations
Transfers: Token transfers within transaction

Example:

{
  "id": 3001,
  "txHash": "5K7Wv8X9YbN3cPdQ6tRzH4mEfJsL2kUiG1nVpWqXoAy",
  "blockchain": "SOLANA",
  "status": "CONFIRMED",
  "confirmations": 64,
  "blockNumber": 123456789
}

Wallet Perspective

How a specific wallet views a chain transaction (inflow or outflow). Direction:

IN - Received tokens (inflow)
OUT - Sent tokens (outflow)

Purpose: Multi-wallet view of same transaction Example:

Chain Transaction: A → B (5 USDC)

Wallet A Perspective:
  Direction: OUT
  Amount: -5 USDC

Wallet B Perspective:
  Direction: IN
  Amount: +5 USDC

Yield & Performance

APY (Annual Percentage Yield)

The annualized rate of return, expressed as a percentage. Format: Percentage string (e.g., "6.0" for 6% APY) Types:

Current APY: Current earning rate
Average APY: Historical average
Weighted Avg APY: Average weighted by allocation size

Display: Append ”%” → “6.0%” Calculation: parseFloat("6.0") / 100 = 0.06 (6%)

Principal

The original amount of funds deployed, excluding yield earned. Calculation: Principal = Total Balance - Cumulative Yield Example:

Deployed: 100 USDC
Yield Earned: 2 USDC
Current Total: 102 USDC
Principal: 100 USDC (original amount)

Yield

Cumulative earnings from yield protocols. Calculation: Tracked via YieldSnapshot records Components:

Lifetime Yield: Total earned since inception
Daily Yield: Last 24 hours
Monthly Yield: Last 30 days

ROI (Return on Investment)

Percentage return on principal. Formula: ROI = (Yield / Principal) × 100 Example:

Principal: 100 USDC
Yield: 5 USDC
ROI: 5%

Custody & Agents

Custody Platform

The infrastructure that stores private keys and signs transactions. Types:

Third-Party: Fireblocks, BitGo, Tatum, Privy
Custom: Your own HSM, MPC, or signing infrastructure
RebelFi Agent: Using RebelFi’s agent with your credentials

Configuration: Set up in dashboard or via API

Agent

A service that polls RebelFi for unsigned transactions, signs them, and reports execution. Types:

RebelFi Managed: RebelFi runs the agent
Customer Managed: You run your own polling service

Responsibilities:

Poll for work (POST /api/agent/transactions/poll)
Sign transactions (via custody solution)
Report execution (POST /api/agent/transactions/:id/report)

Polling Frequency: 10-30 seconds recommended

Lease

A time-bound claim on a transaction attempt. Duration: Set in poll request (e.g., 30000ms = 30 seconds) Purpose: Prevents duplicate execution by multiple agents Expiry: If not reported within lease duration, transaction becomes available again Example:

{
  "leaseDurationMs": 30000,
  "leaseExpiresAt": "2025-01-30T14:01:30Z"
}

Data Types

Amount

Standard format for monetary values. Format:

{
  "amount": "1.11",      // Decimal string
  "currency": "USDC"     // Token symbol
}

See Data Types Reference

Timestamp

Dual-format timestamps. Format:

{
  "iso": "2025-01-30T10:30:00Z",   // ISO 8601
  "unix": 1706611800                // Unix epoch (seconds)
}

See Data Types Reference

Common Acronyms

Acronym	Full Term	Description
APY	Annual Percentage Yield	Annualized rate of return
ATA	Associated Token Account	Solana token account
JWT	JSON Web Token	Authentication token for dashboard
MPC	Multi-Party Computation	Distributed key management
HSM	Hardware Security Module	Physical device for key storage
ROI	Return on Investment	Percentage return on principal
TVL	Total Value Locked	Total value in protocol

Visual Example: Complete Flow

1. Import Wallet (Org Wallet)
   → Address: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin

2. Enable Monitoring (Operational Wallet)
   → Buffer: 0.1 USDC
   → OpWalletId: 456

3. Funds Arrive (Position)
   → Total: 10 USDC
   → Available: 10 USDC
   → Allocated: 0 USDC

4. Operation Created (SUPPLY)
   → Type: SUPPLY
   → Amount: 9.9 USDC (total - buffer)
   → Status: PLANNED

5. Reservation Created
   → Amount: 9.9 USDC (ACTIVE)
   → Available: 0.1 USDC
   → Reserved: 9.9 USDC

6. Agent Execution
   → Poll: GET unsigned transaction
   → Sign: Via your custody
   → Report: Submit txHash

7. Allocation Created
   → Principal: 9.9 USDC
   → Yield: 0 USDC (initially)
   → Status: ACTIVE

8. Yield Accrues
   → Principal: 9.9 USDC (unchanged)
   → Yield: 0.1 USDC (earned)
   → Current APY: 6.0%
   → Total Value: 10.0 USDC

9. Reservation Consumed
   → Status: CONSUMED
   → Available: 0.1 USDC
   → Reserved: 0 USDC
   → Allocated: 10.0 USDC (9.9 principal + 0.1 yield)

Custom Custody Integration - Complete integration guide
Data Types Reference - Standard data formats
Operations API - Operation management
How It Works - Architecture overview

Getting Started

Integration

Use Cases

Concepts

Wallets & Accounts

Organization (Org)

Org Wallet (Organization Wallet)

Operational Wallet (OpWallet)

Financial Concepts

Buffer Amount

Position

Reservation

Allocation

Operations

Operation

Operation Step

Transaction Attempt

Blockchain & Transactions

Chain Transaction

Wallet Perspective

Yield & Performance

APY (Annual Percentage Yield)

Principal

Yield

ROI (Return on Investment)

Custody & Agents

Custody Platform

Agent

Lease

Data Types

Amount

Timestamp

Common Acronyms

Visual Example: Complete Flow

Getting Started

Integration

Use Cases

Concepts

​Wallets & Accounts

​Organization (Org)

​Org Wallet (Organization Wallet)

​Operational Wallet (OpWallet)

​Financial Concepts

​Buffer Amount

​Position

​Reservation

​Allocation

​Operations

​Operation

​Operation Step

​Transaction Attempt

​Blockchain & Transactions

​Chain Transaction

​Wallet Perspective

​Yield & Performance

​APY (Annual Percentage Yield)

​Principal

​Yield

​ROI (Return on Investment)

​Custody & Agents

​Custody Platform

​Agent

​Lease

​Data Types

​Amount

​Timestamp

​Common Acronyms

​Visual Example: Complete Flow

​Related Documentation

Wallets & Accounts

Organization (Org)

Org Wallet (Organization Wallet)

Operational Wallet (OpWallet)

Financial Concepts

Buffer Amount

Position

Reservation

Allocation

Operations

Operation

Operation Step

Transaction Attempt

Blockchain & Transactions

Chain Transaction

Wallet Perspective

Yield & Performance

APY (Annual Percentage Yield)

Principal

Yield

ROI (Return on Investment)

Custody & Agents

Custody Platform

Agent

Lease

Data Types

Amount

Timestamp

Common Acronyms

Visual Example: Complete Flow

Related Documentation