API Reference

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`

All endpoints are versioned with /v0/ prefix.

OpenAPI specification

The complete OpenAPI 3.0 specification is published alongside this documentation:

Download OpenAPI 3.0 spec

Feed it into openapi-generator (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.

Authentication

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

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:

{
  "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:

{
  "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. 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 walks the full settlement lifecycle and shows where webhook events fit between status transitions.

Introduction

Settlement Requests

Payments

Rates

Disbursements

Webhooks

Sandbox

Introduction

Base URLs

OpenAPI specification

Download OpenAPI 3.0 spec

Authentication

Rate Limits

Endpoints

Settlement Requests

Payments

Webhooks

Response Format

Errors

Reliability

​Introduction

​Base URLs

​OpenAPI specification

Download OpenAPI 3.0 spec

​Authentication

​Rate Limits

​Endpoints

​Settlement Requests

​Payments

​Webhooks

​Response Format

​Errors

​Reliability

Introduction

Base URLs

OpenAPI specification

Authentication

Rate Limits

Endpoints

Settlement Requests

Payments

Webhooks

Response Format

Errors

Reliability