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

# Simple Swap

> One-call endpoint that quotes, generates deposit address, and returns a QR code

## How It Works

```
1. POST /leokit/simple     → Quotes Chainflip & NEAR, picks best, returns deposit + QR
2. User scans QR or sends  → Sends funds to the deposit address
3. POST /leokit/status     → Poll with quote_id for swap completion
```

Compared to the standard multi-step flow (`/quote` → `/deposit`), this reduces two API calls to one. Only works with deposit-address-based protocols (**Chainflip** and **NEAR**).

## Payment URI Standards

The `payment_uri` follows the wallet standard for the source chain:

| Source Chain            | Standard   | Example                                              |
| ----------------------- | ---------- | ---------------------------------------------------- |
| BTC, LTC, DOGE, DASH    | BIP-21     | `bitcoin:bc1q...?amount=0.5`                         |
| ETH, ARB, BASE (native) | EIP-681    | `ethereum:0x...@1?value=500000000000000000`          |
| ETH, ARB, BASE (ERC20)  | EIP-681    | `ethereum:0xTOKEN@1/transfer?address=0x...&uint256=` |
| SOL (native)            | Solana Pay | `solana:So1...?amount=2`                             |
| Other                   | Fallback   | Plain deposit address                                |

## Example: BTC to ETH

```bash theme={null}
curl -X POST https://api.leokit.dev/leokit/simple \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_API_KEY" \
  -d '{
    "from_asset": "BTC.BTC",
    "to_asset": "ETH.ETH",
    "amount": "0.01",
    "from_address": "bc1q...",
    "to_address": "0x1234567890AbcdEF1234567890aBcdef12345678"
  }'
```

## Errors

| Status | Code                 | Description                                                               |
| ------ | -------------------- | ------------------------------------------------------------------------- |
| `400`  | `INVALID_ASSET`      | `from_asset` or `to_asset` is malformed or not in the supported list      |
| `400`  | `INVALID_ADDRESS`    | `from_address` or `to_address` not valid for the source/destination chain |
| `400`  | `UNSUPPORTED_PAIR`   | No deposit-address-based route (Chainflip/NEAR) available for the pair    |
| `401`  | `INVALID_API_KEY`    | Missing or invalid `Api-Key` header                                       |
| `404`  | `NO_QUOTE_AVAILABLE` | All deposit-address protocols rejected the pair                           |
| `500`  | `INTERNAL_ERROR`     | Quote or deposit generation failed unexpectedly                           |

See the [error codes catalog](/reference/error-codes) for the full list.


## OpenAPI

````yaml /api-reference/openapi.json POST /simple
openapi: 3.0.3
info:
  title: Leokit API
  version: 1.0.0
  description: API reference for Leokit
servers:
  - url: https://api.leokit.dev
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /simple:
    post:
      summary: Simple swap
      description: >-
        One-call endpoint that quotes deposit-address protocols (Chainflip and
        NEAR), picks the best quote, generates a deposit address, and returns a
        QR code — all in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleRequest'
            example:
              from_asset: ETH.ETH
              to_asset: ARB.USDC-0xaf88d065e77c8cC2239327C5EDb3A432268e5831
              amount: '0.5'
              from_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'
              to_address: '0x1234567890AbcdEF1234567890aBcdef12345678'
              slippage_bps: '100'
      responses:
        '200':
          description: Simple swap response with quote, deposit address, and QR code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
              example:
                quote_id: 01936b4a-7c8e-7890-abcd-ef1234567890
                protocol: chainflip
                deposit_address: '0x8a3c1f2d4e5f67890abcdef1234567890abcdef1'
                amount: '0.5'
                amount_raw: '500000000000000000'
                decimals: 18
                from_asset: ETH.ETH
                to_asset: ARB.USDC-0xaf88d065e77c8cC2239327C5EDb3A432268e5831
                network: ETH
                expected_amount_out: 499.5
                expected_amount_out_usd: 499.5
                total_swap_seconds: 120
                fees:
                  - type: Network Fee
                    asset: ETH
                    amount: 0.001
                    usd: 2.5
                payment_uri: >-
                  ethereum:0x8a3c1f2d4e5f67890abcdef1234567890abcdef1@1?value=500000000000000000
                qr_url: >-
                  https://cdn.leokit.dev/qr/01936b4a-7c8e-7890-abcd-ef1234567890.png
                expires_at: 1707400000
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: >-
                  Missing required params: from_asset, to_asset, amount,
                  from_address, to_address
                code: MISSING_PARAMS
        '404':
          description: No quotes available from Chainflip or NEAR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: No quotes available for this pair
                code: NO_QUOTES
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    SimpleRequest:
      type: object
      description: >-
        Request body for /simple. One-call swap endpoint for deposit-address
        protocols.
      required:
        - from_asset
        - to_asset
        - amount
        - from_address
        - to_address
      properties:
        from_asset:
          type: string
          description: Source asset identifier (CHAIN.SYMBOL-ADDRESS).
          example: ETH.ETH
        to_asset:
          type: string
          description: Destination asset identifier (CHAIN.SYMBOL-ADDRESS).
          example: ARB.USDC-0xaf88d065e77c8cC2239327C5EDb3A432268e5831
        amount:
          type: string
          description: Human-readable amount to swap.
          example: '0.5'
        from_address:
          type: string
          description: Sender address on the source chain (used as refund address).
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'
        to_address:
          type: string
          description: Recipient address on the destination chain.
          example: '0x1234567890AbcdEF1234567890aBcdef12345678'
        slippage_bps:
          type: string
          description: Slippage tolerance in basis points. Defaults to 150 (1.5%).
          example: '100'
    SimpleResponse:
      type: object
      description: Response from /simple containing quote, deposit address, and QR code.
      required:
        - quote_id
        - protocol
        - deposit_address
        - amount
        - amount_raw
        - decimals
        - from_asset
        - to_asset
        - network
        - expected_amount_out
        - payment_uri
        - qr_url
      properties:
        quote_id:
          type: string
          format: uuid
          description: Quote identifier for tracking via /status.
        protocol:
          type: string
          enum:
            - chainflip
            - near
          description: Protocol selected (always chainflip or near).
        deposit_address:
          type: string
          description: Address to send funds to.
        amount:
          type: string
          description: Human-readable amount to send.
        amount_raw:
          type: string
          description: Amount in smallest unit (wei, sats, etc.).
        decimals:
          type: integer
          description: Decimal places for the source asset.
        from_asset:
          type: string
          description: Source asset identifier.
        to_asset:
          type: string
          description: Destination asset identifier.
        network:
          type: string
          description: Source chain short name (e.g. ETH, BTC).
        expected_amount_out:
          type: number
          description: Expected output amount (human-readable).
        expected_amount_out_usd:
          type: number
          nullable: true
          description: Expected output in USD.
        total_swap_seconds:
          type: integer
          nullable: true
          description: Estimated swap time in seconds.
        fees:
          type: array
          description: Fee breakdown.
          items:
            $ref: '#/components/schemas/QuoteFee'
        payment_uri:
          type: string
          description: Chain-specific payment URI (BIP-21, EIP-681, or Solana Pay).
        qr_url:
          type: string
          description: CDN URL of a QR code PNG encoding the payment_uri.
        expires_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (seconds) when the deposit channel expires.
    Error:
      type: object
      description: Generic error payload.
      properties:
        message:
          type: string
        code:
          type: string
    QuoteFee:
      type: object
      description: A fee applied to the quote.
      required:
        - type
        - asset
        - amount
        - usd
      properties:
        type:
          type: string
          description: Fee type (e.g., Network Fee, Outbound Fee, Affiliate Fee).
        asset:
          type: string
          description: Fee asset identifier.
        amount:
          type: number
          description: Fee amount denominated in the fee asset.
        usd:
          description: Fee value in USD. Some protocols return this as a string.
          oneOf:
            - type: number
            - type: string
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: 'Demo API-Key (Sandbox): 7037d2b3-9c76-4f62-b730-c544f7570fa4'

````