API Documentation

This documentation describes API and UI purposes.

Get API AccessContact Support

Quick start

Base URL: https://api.bankcaymanislands.com/v1

Authentication

Use a bearer token. Include it in every request:

Authorization: Bearer <YOUR_API_KEY>
Example request
curl -X GET "https://api.bankcaymanislands.com/v1/wallets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json"

Rate limits

Requests are rate-limited per API key. Default limits:

  • Read endpoints: 120 requests / minute
  • Write endpoints: 60 requests / minute
  • Webhook retries: exponential backoff, up to 24 hours

When you exceed the limit, the API returns 429 with a Retry-After header.

Idempotency

For POST requests that create objects, send Idempotency-Key. Repeated requests with the same key return the same result.

Idempotency-Key: 6d2e7a9b-2e2b-4a62-9a51-0c83d8b5bd7c

Errors

All error responses follow this shape:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid amount",
    "request_id": "req_01J9ZQK9Y2S2M0..."
  }
}
  • validation_error — invalid input
  • unauthorized — missing/invalid token
  • insufficient_funds — balance too low
  • rate_limited — too many requests

Pagination

List endpoints use cursor pagination:

GET https://api.bankcaymanislands.com/v1/transfers?limit=25&cursor=tr_01J...
{
  "data": [...],
  "next_cursor": "tr_01J...",
  "has_more": true
}

Wallets

GET/wallets

List wallets for the authenticated account.

Request
curl -X GET "https://api.bankcaymanislands.com/v1/wallets" \
  -H "Authorization: Bearer $API_KEY"
Response
{
  "data": [
    {
      "id": "wal_01J9Z...",
      "currency": "USD",
      "available_balance": "12450.32",
      "hold_balance": "120.00"
    },
    {
      "id": "wal_01J9Z...",
      "currency": "BTC",
      "available_balance": "0.42350000",
      "hold_balance": "0.00000000"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
GET/wallets/{wallet_id}

Get wallet details.

Request
curl -X GET "https://api.bankcaymanislands.com/v1/wallets/wal_01J9Z..." \
  -H "Authorization: Bearer $API_KEY"
Response
{
  "id": "wal_01J9Z...",
  "currency": "EUR",
  "available_balance": "832.12",
  "hold_balance": "0.00",
  "updated_at": "2026-03-02T00:00:00Z"
}

Transfers

POST/transfers

Create a new transfer (crypto or fiat).

Request
curl -X POST "https://api.bankcaymanislands.com/v1/transfers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 7e8b..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "currency": "EUR",
    "destination": {
      "type": "iban",
      "iban": "DE89370400440532013000",
      "system": "SEPA"
    },
    "reference": "Invoice #1024"
  }'
Response
{
  "id": "tr_01JA...",
  "status": "PENDING",
  "amount": "250.00",
  "currency": "EUR",
  "created_at": "2026-03-02T00:00:00Z"
}
GET/transfers

List transfers.

Request
curl -X GET "https://api.bankcaymanislands.com/v1/transfers?limit=25" \
  -H "Authorization: Bearer $API_KEY"
Response
{
  "data": [
    {
      "id": "tr_01JA...",
      "status": "COMPLETED",
      "amount": "0.0100",
      "currency": "BTC",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Payments

POST/payments/intents

Create a payment intent.

Request
curl -X POST "https://api.bankcaymanislands.com/v1/payments/intents" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "99.00",
    "currency": "USD",
    "description": "Subscription",
    "metadata": { "plan": "pro" }
  }'
Response
{
  "id": "pi_01J...",
  "status": "REQUIRES_PAYMENT_METHOD",
  "amount": "99.00",
  "currency": "USD",
  "client_secret": "pi_01J..._secret_..."
}

Webhooks

Webhooks deliver events to your endpoint. Verify signatures using X-Signature.

POST https://yourapp.com/webhooks/boci
X-Signature: t=...,v1=...
POST/webhooks/endpoints

Register a webhook endpoint.

Request
curl -X POST "https://api.bankcaymanislands.com/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/boci",
    "events": ["transfer.completed", "payment.failed"]
  }'
Response
{
  "id": "wh_01J...",
  "url": "https://yourapp.com/webhooks/boci",
  "events": ["transfer.completed", "payment.failed"],
  "created_at": "2026-03-02T00:00:00Z"
}

Changelog

  • 2026-02-11 — Initial public API draft
  • 2025-12-28 — Added idempotency keys and webhook retries
  • 2025-10-20 — Introduced cursor pagination for list endpoints
Looking for help? Visit Support Center.