# Kaito Developer Portal

Welcome to the Kaito APIs. This portal provides OpenAPI specs, quickstarts, and security details so you can build, test, and launch on Kaito.

## What is Kaito?

Kaito provides **API-based connectivity** as a **payment rail** to move value across regions and rails:

- **FIAT <-> FIAT** — Cross-border fiat transfers
- **FIAT <-> CRYPTO** — On-ramp to crypto
- **CRYPTO <-> FIAT** — Off-ramp to fiat
- **CRYPTO <-> CRYPTO** — On-chain transfers


You integrate once with the Kaito API, and Kaito handles routing, provider selection, fallbacks, and settlement orchestration.

## Integration Options

| Option | Description | Use Case |
|  --- | --- | --- |
| **API Direct** | Full control via REST API | Backend integrations |
| **JavaScript SDK** | `@kaito/checkout-sdk` | Web applications |
| **Hosted Checkout** | Redirect to Kaito | Quick integration |
| **iFrame Embed** | Widget in your app | Custom UI |


## Environments

| Environment | Base URL | Purpose |
|  --- | --- | --- |
| **Production** | `https://api.kai2.io` | Live transactions |
| **Sandbox** | `https://sandbox.api.kai2.io` | Testing with mock data |


## API Catalog

### Core API

Quotes, payments, payouts, and FX operations.

| Feature | Description |
|  --- | --- |
| **Quotes** | Lock pricing and routing for a limited time window |
| **Execution Plans** | Preview the multi-hop execution path |
| **Payments** | Execute on-ramp (FIAT_CRYPTO) and on-chain (CRYPTO_CRYPTO) payments |
| **Payouts** | Execute off-ramp (CRYPTO_FIAT) and cross-border (FIAT_FIAT) payouts |
| **FX Rates** | Indicative exchange rates |
| **FX Quotes** | Firm, executable FX quotes |
| **Corridors** | Supported country pairs and rails |


**Spec:** [`core.yaml`](/core)

### Users API

Identity verification, wallet management, and directory services.

| Feature | Description |
|  --- | --- |
| **Identity (KYC)** | Individual identity verification |
| **Identity (KYB)** | Business verification |
| **Wallets** | Custodial wallet creation and management |
| **Directory Resolution** | Resolve handles, phone numbers, emails to wallet addresses |
| **Handles** | Manage user handles/aliases |
| **Contacts** | Address book management |


**Spec:** [`users.yaml`](/users)

### Merchant API

Payment acceptance and banking services for merchants.

| Feature | Description |
|  --- | --- |
| **Charges** | In-person payment acceptance (NFC, QR, Alias) |
| **Refunds** | Full or partial refunds |
| **Merchants** | Merchant account management |
| **Settlements** | View settlement history and status |
| **Balances** | Available and pending balances |
| **Reconciliation** | Daily reports (CSV, XLSX, JSON) |
| **Fees** | Fee breakdown and summaries |


**Spec:** [`merchant.yaml`](/merchant)

### Platform API

Webhooks and blockchain gateway operations.

| Feature | Description |
|  --- | --- |
| **Webhook Endpoints** | Register and manage webhook subscriptions |
| **Event Types** | List available event types |
| **Fee Estimation** | Estimate network fees before transactions |
| **Transaction Broadcast** | Submit signed transactions to blockchain networks |


**Spec:** [`platform.yaml`](/platform)

## Security

| Mechanism | Description |
|  --- | --- |
| **OAuth2** | Client credentials from `https://auth.kai2.io/oauth2/token` |
| **mTLS** | Client certificate required on every request |
| **Scopes** | Request only needed scopes (e.g., `payments:write`) |
| **Idempotency** | `Idempotency-Key` header for safe retries |
| **Webhooks** | HMAC-SHA256 signature verification |


## Quick Start


```bash
# 1. Get access token
curl -X POST https://auth.kai2.io/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "audience=https://api.kai2.io"

# 2. Create a quote
curl -X POST https://sandbox.api.kai2.io/v1/quotes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "railType": "FIAT_CRYPTO",
    "sender": { "amount": "100", "currency": "USD" },
    "receiver": { "currency": "USDT" },
    "corridor": "US-GT"
  }'

# 3. Execute payment
curl -X POST https://sandbox.api.kai2.io/v1/payments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "railType": "FIAT_CRYPTO",
    "amount": 100,
    "currency": "USD",
    "destination": { "type": "address", "value": "0x..." },
    "quoteId": "qt_01JH..."
  }'
```

## SDKs & Tools

- Auto-generate clients from OpenAPI specs (TypeScript, Python, Java, Go)
- Import specs into Postman/Insomnia


## Documentation

- [Overview](/docs/00-overview) — Key concepts and architecture
- [Payment Rail](/docs/10-payment-rail) — How Kaito works as a rail
- [Embedded Experiences](/docs/20-embedded-experiences) — SDK, Checkout, iFrame
- [Use Cases](/docs/30-use-cases) — Example flows
- [Webhooks](/docs/40-webhooks) — Event delivery and signatures
- [Errors & Tracing](/docs/50-errors-and-tracing) — Error handling


*Last updated: 2025-12-22*