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

# API Reference

> Complete reference for all Superbank API endpoints

## Introduction

The Superbank API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

## Base URLs

| Environment | Base URL                           |
| ----------- | ---------------------------------- |
| Sandbox     | `https://api-sandbox.superbank.co` |
| Production  | `https://api.superbank.co`         |

<Info>All endpoints are versioned with `/v0/` prefix.</Info>

## OpenAPI specification

The complete OpenAPI 3.0 specification is published alongside this documentation:

<Card title="Download OpenAPI 3.0 spec" icon="download" href="/openapi/v0/openapi.json">
  Feed it into [`openapi-generator`](https://openapi-generator.tech/) (or any compatible tool) to
  generate a typed client in TypeScript, Go, Python, or any other supported language. The file is
  regenerated on every release.
</Card>

## Authentication

All API requests require an API key passed in the `X-Api-Key` header:

```bash theme={null}
curl https://api-sandbox.superbank.co/v0/settlement-requests \
  -H "X-Api-Key: sk_sandbox_your-api-key"
```

## Rate Limits

| Environment | Requests/Minute |
| ----------- | --------------- |
| Sandbox     | 100             |
| Production  | 1000            |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

## Endpoints

### Settlement Requests

| Method | Endpoint                       | Description                      |
| ------ | ------------------------------ | -------------------------------- |
| `POST` | `/v0/settlement-requests`      | Create a settlement request      |
| `GET`  | `/v0/settlement-requests`      | List settlement requests         |
| `GET`  | `/v0/settlement-requests/{id}` | Retrieve a settlement request    |
| `PUT`  | `/v0/settlement-requests/{id}` | Update settlement request status |

### Payments

| Method | Endpoint            | Description        |
| ------ | ------------------- | ------------------ |
| `GET`  | `/v0/payments`      | List all payments  |
| `GET`  | `/v0/payments/{id}` | Retrieve a payment |

### Webhooks

| Method   | Endpoint            | Description                 |
| -------- | ------------------- | --------------------------- |
| `POST`   | `/v0/webhooks`      | Create a webhook endpoint   |
| `GET`    | `/v0/webhooks`      | List webhook endpoints      |
| `GET`    | `/v0/webhooks/{id}` | Retrieve a webhook endpoint |
| `PATCH`  | `/v0/webhooks/{id}` | Update a webhook endpoint   |
| `DELETE` | `/v0/webhooks/{id}` | Delete a webhook endpoint   |

## Response Format

All responses are returned in JSON format with `snake_case` field names:

```json theme={null}
{
  "id": "pay_abc123",
  "type": "OUTBOUND_SETTLEMENT",
  "status": "COMPLETED",
  "amount": "100.00",
  "currency_code": "USDC",
  "created_at": "2024-01-15T10:00:00Z"
}
```

## Errors

Error responses include a status code and message:

```json theme={null}
{
  "status_code": 400,
  "message": "Bad Request",
  "error": "Validation failed"
}
```

## Reliability

Superbank is designed to make integrations resilient by default.

* **Webhooks for state changes.** Subscribe an endpoint to be notified the moment a settlement, payment, or pool changes state — see the **[Webhooks guide](/platform/guides/webhook-guide)**. Polling is supported as a fallback but webhooks have lower latency and don't burn rate-limit budget.
* **Lifecycle reference.** The **[Real-Time On-Ramping guide](/platform/guides/real-time-on-ramping)** walks the full settlement lifecycle and shows where webhook events fit between status transitions.