> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rebelfi.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Architecture, data flow, and fee model for the RebelFi ramp

## Supported Chains

| Blockchain | Status |
| ---------- | ------ |
| Polygon    | Live   |
| Arbitrum   | Live   |
| Base       | Live   |
| Ethereum   | Live   |
| Solana     | Live   |

## Architecture

RebelFi is the orchestration layer between your platform and banking infrastructure. You talk only to our API — we handle KYB, account issuance, conversion, and delivery.

<CardGroup cols={3}>
  <Card title="Your Platform" icon="laptop-code">
    Calls the RebelFi API to create recipients, provision accounts, query transactions, and receive webhook events
  </Card>

  <Card title="RebelFi" icon="arrows-left-right">
    Orchestrates KYB, account issuance, conversion tracking, and event delivery
  </Card>

  <Card title="Banking Infrastructure" icon="building-columns">
    Handles virtual bank accounts, USD receipt, and conversion
  </Card>
</CardGroup>

Your Platform **⟷** RebelFi **⟷** Banking Infrastructure — connected via API + webhooks at each layer. You talk only to RebelFi.

## Data Flow

### On-Ramp (USD → USDC/USDT)

When a payer sends USD to a recipient's virtual bank account, the funds are automatically converted to the configured stablecoin (USDC or USDT) and delivered to the designated wallet.

```
Payer                    Virtual Bank Account              Designated Wallet
(sends USD)              (per account, US bank)            (USDC or USDT)

  $50,000 USD ────────►  Account receives funds ────────►  $49,875 USDC/USDT delivered
  (ACH, Wire, or SWIFT)  Auto-converts USD → stablecoin    (fee deducted)
```

### Off-Ramp (USDC/USDT → USD)

When stablecoins are sent to an off-ramp account's deposit address, the funds are converted to USD and delivered to the configured bank account.

```
Source Wallet            Crypto Deposit Address            Bank Account
(sends USDC/USDT)        (per account)                     (USD)

  $50,000 USDC ────────►  Account receives crypto ────────►  $49,875 USD delivered
                           Auto-converts to USD               (fee deducted, via ACH/Wire/SWIFT)
```

## Fee Model

A percentage-based fee is deducted from each transaction before delivery. The fee is expressed in basis points (bps) and applies to both on-ramp and off-ramp.

**Example** — \$50,000 transaction at 25 bps total fee:

|              | Amount      |
| ------------ | ----------- |
| Amount in    | \$50,000.00 |
| Fee (25 bps) | \$125.00    |
| Delivered    | \$49,875.00 |

Fees are deducted automatically — no invoicing required.

## Payment Rails

Each ramp account is created with a specific payment rail:

| Rail      | Description                                        |
| --------- | -------------------------------------------------- |
| `ach`     | ACH transfer — standard US bank transfer (default) |
| `fedwire` | Fedwire — same-day US wire transfer                |
| `swift`   | SWIFT — international wire transfer                |

You select the rail when creating each on-ramp or off-ramp account.

## Wallet Model

Each ramp account is bound to a specific wallet:

* **On-ramp accounts** have a **destination wallet** — where USDC/USDT is delivered
* **Off-ramp accounts** have a **source wallet** — where USDC/USDT is sent from

A single recipient can have multiple on-ramp and off-ramp accounts, each targeting different wallets, assets, or networks.

## Recipient Lifecycle

```
Create Recipient ──► KYB Pending ──► KYB Submitted ──► KYB Approved ──► Create Accounts
                                                   └──► KYB Declined
```

1. You create a recipient via `POST /v1/ramp/recipients` (optionally with address)
2. RebelFi returns a hosted KYB URL
3. The recipient completes the KYB form
4. On approval, RebelFi sends a `customer.approved` webhook
5. You create on-ramp and/or off-ramp accounts for the recipient

<Info>
  Accounts are not auto-created — you explicitly create them after KYB approval. This gives you full control over which recipients get which account types.
</Info>

## Transaction Lifecycle

Once a recipient has an active account, transactions flow through these states:

| Status       | Meaning                                         |
| ------------ | ----------------------------------------------- |
| `pending`    | Deposit detected, conversion not yet started    |
| `processing` | Conversion in progress                          |
| `completed`  | Funds delivered                                 |
| `failed`     | Conversion failed — review required             |
| `reversed`   | Deposit was reversed — funds returned to sender |

RebelFi sends webhook events on every state change so you can track progress in real time.