# Ramps List

Retrieve a paginated list of transfer orders (ramps).
**Pagination Modes**:
- **Cursor Pagination**: Use `startAfter`, `endBefore`, or `cursor` parameters. Dates are optional.
- **Offset Pagination**: Use `page` parameter. Dates (`dateFrom` and `dateTo`) are required.

**Important**: Cannot mix pagination types. Choose either cursor-based or offset-based pagination.
**Use Cases**:
- Retrieve transaction history for reporting
- Sync transactions to your system
- Display transaction list to customers
- Export transaction data

Endpoint: GET /eapi/v0/ramps
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Query parameters:

  - `perPage` (integer)
    Number of items per page.

**Range**: 1-200
**Default**: 10

**Recommendation**: Use smaller page sizes (10-50) for better performance.

  - `page` (integer)
    Page number for offset pagination (1-based).

**Offset Pagination Mode**:
- Cannot be used with cursor parameters (`startAfter`, `endBefore`, `cursor`)
- **Requires** `dateFrom` and `dateTo` when used
- Returns total count and page information
- Suitable for UI pagination with page numbers

**Example**: `page=2&perPage=25&dateFrom=2024-01-01&dateTo=2024-12-31`

  - `startAfter` (string)
    Cursor to start after (order key or ID). Returns orders after this cursor, excluding it.

**Cursor Pagination Mode**:
- Cannot be used with `endBefore` or `page`
- Dates are optional when using cursor pagination
- More efficient for large datasets
- Suitable for infinite scroll or "load more" patterns

**Example**: `startAfter=ORD-2024-100&perPage=25`

  - `endBefore` (string)
    Cursor to end before (order key or ID). Returns orders before this cursor, excluding it.

**Cursor Pagination Mode**:
- Cannot be used with `startAfter` or `page`
- Dates are optional when using cursor pagination
- Useful for reverse pagination

**Example**: `endBefore=ORD-2024-200&perPage=25`

  - `cursor` (string)
    Generic cursor parameter for pagination (typically from previous response).

**Usage**:
- Cannot be used with `page`
- Dates are optional when using cursor pagination
- Use `nextCursor` or `prevCursor` from previous response
- Opaque string - do not parse or modify

**Example**: `cursor=eyJvcmRlcnMuaWQiOjEyMzQ1fQ==`

  - `dateFrom` (string)
    Start date filter (YYYY-MM-DD).

**Requirements**:
- **Required** for offset pagination (when using `page`)
- **Optional** for cursor pagination (when using `startAfter`, `endBefore`, or `cursor`)

**Validation**:
- Must be valid date in YYYY-MM-DD format
- Cannot be in the future
- Must be <= `dateTo` if both provided

  - `dateTo` (string)
    End date filter (YYYY-MM-DD). Must be >= `dateFrom` if provided.

**Requirements**:
- **Required** for offset pagination (when using `page`)
- **Optional** for cursor pagination (when using `startAfter`, `endBefore`, or `cursor`)

**Validation**:
- Must be valid date in YYYY-MM-DD format
- Must be >= `dateFrom`
- Cannot be in the future

## Response 200:

  - `200` (unknown)
    Successful response with paginated ramps list.
**Response Structure**:
- `data`: Array of ramp objects
- `pagination`: Pagination metadata (cursor or offset based)

**Pagination Metadata**:
- **Cursor mode**: `nextCursor`, `prevCursor`, `hasMore`, `perPage`
- **Offset mode**: `currentPage`, `perPage`, `total`, `lastPage`, `from`, `to`

## Response 200 fields (application/json):

  - `data` (array, required)
    Array of ramp transaction objects

  - `data.id` (string, required)
    Unique order identifier (order key)
    Example: ORD-2024-12345

  - `data.subPartnerId` (string | null)
    Sub-partner identifier if applicable
    Example: partner-123

  - `data.identityReference` (string | null)
    Customer identity reference
    Example: customer-12345

  - `data.status` (string, required)
    Current status of the ramp transaction
    Enum: "pending", "processing", "completed", "cancelled", "failed"

  - `data.source` (any, required)
    Source of the transfer (fiat for on-ramp, crypto for off-ramp)

  - `data.source.fiat` (object, required)

  - `data.source.fiat.id` (string, required)
    Fiat currency code
    Example: USD

  - `data.source.fiat.method` (string, required)
    Payment method
    Example: card

  - `data.source.amount` (string, required)
    Source amount
    Example: 1000.00

  - `data.source.crypto` (object, required)

  - `data.source.crypto.id` (string, required)
    Cryptocurrency code
    Example: BTC

  - `data.source.crypto.blockchain` (string, required)
    Blockchain network
    Example: BTC

  - `data.source.crypto.walletAddress` (string)
    Example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

  - `data.source.crypto.walletAddressMemo` (string | null)
    Example: 123456

  - `data.target` (any, required)
    Target of the transfer (crypto for on-ramp, fiat for off-ramp)

  - `data.target.crypto` (object, required)

  - `data.target.crypto.id` (string, required)
    Cryptocurrency code
    Example: ETH

  - `data.target.crypto.blockchain` (string, required)
    Blockchain network
    Example: ETH

  - `data.target.crypto.walletAddress` (string)
    Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

  - `data.target.crypto.walletAddressMemo` (string | null)
    Example: 100547087

  - `data.target.amount` (string, required)
    Target amount
    Example: 0.5

  - `data.target.fiat` (object, required)

  - `data.target.fiat.id` (string, required)
    Fiat currency code
    Example: EUR

  - `data.target.fiat.method` (string, required)
    Payment method
    Example: bank_transfer

  - `data.receipt` (object, required)
    Transaction receipt with fees and hashes

  - `data.receipt.targetTransactionHash` (string | null)
    Blockchain transaction hash for target (on-ramp)
    Example: 0xabc123def456789...

  - `data.receipt.sourceTransactionHash` (string | null)
    Blockchain transaction hash for source (off-ramp)
    Example: 0x789def456abc123...

  - `data.receipt.gatewayFee` (string | null)
    Example: 5.00

  - `data.receipt.networkFee` (string | null)
    Example: 2.50

  - `data.receipt.sourceAmount` (string | null)
    Example: 1000.00

  - `data.receipt.targetAmount` (string | null)
    Example: 0.025

  - `data.createdAt` (string, required)
    Order creation timestamp (ISO 8601 UTC)
    Example: 2024-01-15T10:30:00Z

  - `data.completedAt` (string | null)
    When the transaction was completed (null if not completed)
    Example: 2024-01-15T10:45:00Z

  - `pagination` (any, required)
    Pagination information - either cursor-based or offset-based

  - `pagination.nextCursor` (string | null)
    Cursor for the next page. Null if no more pages.
    Example: eyJvcmRlcnMuaWQiOjEyMzQ1LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9

  - `pagination.prevCursor` (string | null)
    Cursor for the previous page. Null if on first page.
    Example: eyJvcmRlcnMuaWQiOjEyMzQ1LCJfcG9pbnRzVG9OZXh0SXRlbXMiOmZhbHNlfQ==

  - `pagination.hasMore` (boolean, required)
    Indicates if there are more results available after the current page.
**Usage**: Use this to show/hide "Load More" button in UI.
    Example: true

  - `pagination.perPage` (integer, required)
    Number of items per page (as requested or default)
    Example: 10

  - `pagination.currentPage` (integer, required)
    Current page number (1-based)
    Example: 1

  - `pagination.perPage` (integer, required)
    Number of items per page
    Example: 10

  - `pagination.total` (integer, required)
    Total number of items across all pages
    Example: 150

  - `pagination.lastPage` (integer, required)
    Last page number (total pages)
    Example: 15

  - `pagination.from` (integer | null)
    Index of first item on current page (1-based). Null if no results.
    Example: 1

  - `pagination.to` (integer | null)
    Index of last item on current page (1-based). Null if no results.
    Example: 10

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 422:

  - `422` (unknown)
    Validation error - request is well-formed but contains invalid data.
**Common Causes**:
- Field validation failures
- Business rule violations
- Invalid field combinations
- Out of range values

## Response 422 fields (application/json):

  - `message` (string)
    Summary of validation errors
    Example: The given data was invalid.

  - `errors` (object)
    Map of field names to error messages.
**Format**: Each key is a field name, value is an array of error messages for that field.
    Example: {"email":["The email field is required."],"fiatAmount":["The fiat amount must be at least 10."]}

  - `code` (integer)
    HTTP status code
    Example: 422

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429:

  - `429` (unknown)
    Rate limit exceeded.
**Rate Limits**:
- General API: 100 requests per minute
- Price endpoint: 60 requests per minute

**Action**: Wait for the duration specified in `Retry-After` header before retrying.

## Response 429 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Too Many Requests. Please try again later.

  - `code` (integer)
    HTTP status code
    Example: 429

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying.

**Important**: Always respect this header to avoid further rate limiting.
    Example: 60

## Response 500:

  - `500` (unknown)
    Unexpected server error.
**Action**:
- Retry with exponential backoff (up to 3 attempts)
- If error persists, contact support with the traceId

**Note**: This is a temporary issue on our side, not a problem with your request.

## Response 500 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Server Error

  - `code` (integer)
    HTTP status code
    Example: 500

  - `traceId` (string)
    Unique identifier for this error instance. **Important**: Include this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 200 examples:

  - `Cursor pagination response` (unknown)
    Example response using cursor-based pagination. Use nextCursor for next page.

  - `Offset pagination response` (unknown)
    Example response using offset-based pagination. Use page parameter for navigation.