> ## 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.

# API Introduction

> RebelFi REST API basics: authentication, base URL, and response format

## Base URL

All API requests use the following base URL:

```
https://api.rebelfi.io/v1
```

## Authentication

Authenticate all requests with your API key in the `x-api-key` header:

```bash theme={null}
curl -X GET "https://api.rebelfi.io/v1/venues" \
  -H "x-api-key: your_api_key_here"
```

There are two types of API keys:

* **Profile-scoped keys** — Tied to a Wallet Profile. Can read and write (register wallets, plan operations, submit transactions) within that profile.
* **Admin keys** — Organization-wide, read-only. Can list wallets and view aggregate data across all profiles. Cannot create wallets or operations.

See [Authentication](/guides/authentication) for details on generating each type.

<Warning>
  Keep your API key secure. Never expose it in client-side code or commit it to version control.
</Warning>

## Response Format

### Success Responses

Successful responses return data directly (no envelope):

```json theme={null}
{
  "venues": [...],
  "count": 2,
  "strategyCount": 4
}
```

HTTP status codes:

* `200 OK` - Request succeeded
* `201 Created` - Resource created
* `202 Accepted` - Request accepted for processing

### Error Responses

Error responses include a message and error code:

```json theme={null}
{
  "statusCode": 400,
  "message": "Insufficient balance for operation",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "required": "1000000000",
    "available": "500000000"
  }
}
```

HTTP status codes:

* `400 Bad Request` - Invalid parameters
* `401 Unauthorized` - Invalid or missing API key
* `403 Forbidden` - API key disabled
* `404 Not Found` - Resource not found
* `429 Too Many Requests` - Rate limit exceeded
* `500 Internal Server Error` - Server error

## Error Codes

| Code                          | Description                                         |
| ----------------------------- | --------------------------------------------------- |
| `INVALID_AMOUNT`              | Amount is zero, negative, or malformed              |
| `INVALID_ADDRESS`             | Wallet address format is invalid                    |
| `INVALID_TOKEN`               | Token address not recognized                        |
| `INSUFFICIENT_BALANCE`        | Wallet balance too low                              |
| `STRATEGY_NOT_ACTIVE`         | Strategy is paused                                  |
| `ALLOCATION_NOT_FOUND`        | No position at this venue                           |
| `OPERATION_EXPIRED`           | Unsigned transaction expired                        |
| `OPERATION_ALREADY_SUBMITTED` | Transaction already submitted                       |
| `TOKEN_MISMATCH`              | Token doesn't match strategy                        |
| `INVALID_OPERATION_STATUS`    | Operation in wrong state for requested action       |
| `OPERATION_IN_PROGRESS`       | Another operation is executing for this wallet      |
| `VENUE_NOT_FOUND`             | Venue ID doesn't exist                              |
| `STRATEGY_NOT_FOUND`          | Strategy ID doesn't exist                           |
| `OPERATION_NOT_FOUND`         | Operation ID doesn't exist                          |
| `TRANSACTION_NOT_FOUND`       | Transaction ID doesn't exist                        |
| `WALLET_NOT_FOUND`            | Wallet not registered                               |
| `ORGANIZATION_NOT_FOUND`      | Organization not found for API key                  |
| `TOKEN_NOT_FOUND`             | Token not supported                                 |
| `INSUFFICIENT_GAS`            | Not enough native token for fees (ETH, POL, or SOL) |
| `SIMULATION_FAILED`           | Transaction simulation failed                       |
| `INVALID_API_KEY`             | API key not recognized                              |
| `API_KEY_DISABLED`            | API key has been revoked                            |
| `RATE_LIMIT_EXCEEDED`         | Too many requests                                   |

## Rate Limits

API requests are rate limited per API key:

| Endpoint Type | Limit               |
| ------------- | ------------------- |
| Read (GET)    | 100 requests/minute |
| Write (POST)  | 20 requests/minute  |

When rate limited, you'll receive a `429` response with `RATE_LIMIT_EXCEEDED` code. Implement exponential backoff for retries.

## Amount Convention

All monetary amounts in the API are represented as strings in **base units** (smallest denomination).

| Token | Decimals | 1 Token in Base Units | Example                |
| ----- | -------- | --------------------- | ---------------------- |
| USDC  | 6        | `"1000000"`           | `"5000000"` = 5 USDC   |
| USDT  | 6        | `"1000000"`           | `"10000000"` = 10 USDT |

Amounts are always strings, never numbers, to preserve precision.

## Transaction Submission

After signing a transaction, you have two options:

| Method          | When to Use                                                                                                                                                    |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `submit-signed` | You want RebelFi to broadcast the transaction to the blockchain. Send the signed transaction bytes and RebelFi handles broadcasting and confirmation tracking. |
| `submit-hash`   | You broadcast the transaction yourself (e.g., via your own RPC node) and just send RebelFi the transaction hash so it can track confirmation.                  |

Most integrations should use `submit-signed` for simplicity. Use `submit-hash` if you need control over the broadcast (e.g., priority fees, custom RPC endpoints).

## Sandbox Environment

For testing, use the sandbox base URL:

```
https://sandbox-api.rebelfi.io/v1
```

Sandbox API keys have the prefix `rfk_sandbox_`. See the [Sandbox guide](/guides/sandbox) for details.

## Supported Blockchains

| Blockchain | Token Support | Status      |
| ---------- | ------------- | ----------- |
| Solana     | USDC, USDT    | Live        |
| Polygon    | USDC, USDT    | Live        |
| Ethereum   | USDC, USDT    | Live        |
| Base       | USDC          | Live        |
| Arbitrum   | USDC, USDT    | Coming Soon |

## Request Examples

### cURL

```bash theme={null}
# List venues (Ethereum)
curl -X GET "https://api.rebelfi.io/v1/venues?blockchain=ethereum&token=USDC" \
  -H "x-api-key: your_api_key"

# Plan supply operation (Ethereum)
curl -X POST "https://api.rebelfi.io/v1/operations/supply" \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "strategyId": 5,
    "amount": "1000000000",
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  }'
```

### JavaScript (fetch)

```javascript theme={null}
const API_KEY = process.env.REBELFI_API_KEY;
const BASE_URL = 'https://api.rebelfi.io/v1';

async function listVenues(blockchain = 'ethereum') {
  const response = await fetch(`${BASE_URL}/venues?blockchain=${blockchain}&token=USDC`, {
    headers: { 'x-api-key': API_KEY }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return response.json();
}
```

### Python (requests)

```python theme={null}
import requests
import os

API_KEY = os.environ['REBELFI_API_KEY']
BASE_URL = 'https://api.rebelfi.io/v1'

def list_venues(blockchain='ethereum'):
    response = requests.get(
        f'{BASE_URL}/venues',
        headers={'x-api-key': API_KEY},
        params={'blockchain': blockchain, 'token': 'USDC'}
    )
    response.raise_for_status()
    return response.json()
```

## Available Resources

| Resource                                                           | Endpoints                                      |
| ------------------------------------------------------------------ | ---------------------------------------------- |
| [Wallets](/api-reference/wallets/register)                         | Register, list, get, update                    |
| [Venues](/api-reference/venues/list)                               | List, get                                      |
| [Allocations](/api-reference/allocations/list)                     | List, get by strategy, earnings                |
| [Operations](/api-reference/operations/supply)                     | Supply, unwind, get, cancel                    |
| [Transactions](/api-reference/transactions/submit-hash)            | Submit hash, submit signed, get, recover       |
| [Ramping — KYB](/api-reference/ramping/start-kyb)                  | Start KYB, get status                          |
| [Ramping — Recipients](/api-reference/ramping/create-recipient)    | Create, list, get, archive                     |
| [Ramping — Accounts](/api-reference/ramping/create-onramp-account) | Create on-ramp, create off-ramp, list off-ramp |
| [Ramping — Transactions](/api-reference/ramping/list-transactions) | List, get, summary                             |
| [Ramping — Simulation](/api-reference/ramping/simulate-onramp)     | Simulate on-ramp, simulate off-ramp            |

## SDK Recommendation

For TypeScript/JavaScript projects, we recommend using the official SDK:

```bash theme={null}
npm install @rebelfi/sdk
```

The SDK provides:

* Full TypeScript types
* Wallet registration and management
* Automatic error handling with `RebelfiError`
* Flexible wallet identification (`walletId`, `walletAddress`, or `userId`)

See the [SDK documentation](/sdk/introduction) for details.