# CryptoSwap API Integration

Build a server-side integration for CryptoSwap. There are two different API surfaces:

1. Public Data API
   - Base URL: https://b1exch.to/api
   - No API key is required.
   - Use only for public display data: rates, liquidity, and public currency metadata.
   - Do not create swaps from public endpoints.

2. Partner API
   - Base URL: https://b1exch.to/api/partner/v1
   - Every request requires an API key, including GET requests.
   - Send the key as either:
     - X-API-Key: b1x_...
     - Authorization: Bearer b1x_...
   - API calls may be sent from clearnet servers or onion hosts when using the matching API hostname supplied by the operator.
   - If the base URL shown here is an .onion URL, clearnet-only servers need the clearnet API hostname before they can call it.
   - Partner portal login is onion-only, but that restriction does not apply to server-to-server API calls.
   - Never expose the API key in frontend JavaScript, mobile apps distributed to users, logs, screenshots, or public repositories.
   - No API key yet? A lifetime partner key can be bought self-serve for $100 in crypto at /buy-api-key on the main site; it is issued automatically once the payment confirms, with no account required.

Optional machine-readable schema:
- https://b1exch.to/api/openapi.json
- Use it only as an additional schema reference. This Markdown is the primary implementation instruction.

Recommended partner integration flow:
1. Verify the key.
   GET /api/partner/v1/me
   Required header: X-API-Key
   Use this to confirm the key works, the partner account is active, scopes are present, commission percent is known, and limits.max_pending_swaps is available.

2. Load partner currencies.
   GET /api/partner/v1/currencies
   Required header: X-API-Key
   Use this to build the swap form. It returns enabled currencies and partner API minimum USD values.

3. Optionally load public display data.
   GET /api/rates
   GET /api/liquidity
   GET /api/currencies
   No API key is required for these endpoints. Use them for UI display only.

4. Preview a quote.
   POST /api/partner/v1/quote
   Required header: X-API-Key
   Body fields:
   - from: source/deposit currency, for example BTC
   - to: destination/output currency, for example LTC
   - amount: source amount the customer is expected to deposit
   - destination: customer payout address for the target currency
   Treat quote responses as indicative only. A quote is not a reservation and does not lock price.

5. Create the live swap.
   POST /api/partner/v1/swaps
   Required header: X-API-Key
   Required body fields:
   - from
   - to
   - amount
   - destination
   - refund_address
   Optional body fields:
   - reference: partner-side order ID, max 100 characters. Use a unique reference per order for retry safety.
   - commission_address: same-chain automatic commission payout address for the source/deposit currency
   Retry behavior: if the same API key repeats POST /swaps with the same reference and identical swap details, return the existing swap instead of creating a duplicate. If the same reference is reused with different details, return HTTP 409 duplicate_reference.
   Store the returned swap ID, deposit address, refund address, destination address, expiry time, and your own reference.

6. Track the swap.
   GET /api/partner/v1/swaps/{id}
   Required header: X-API-Key
   Poll every 20-60 seconds until is_completed is true.

7. Build dashboards or reconciliation tools.
   GET /api/partner/v1/swaps?skip=0&take=50
   GET /api/partner/v1/swaps?status=completed
   Required header: X-API-Key

8. Screen an address for risk before accepting or paying to it (optional).
   GET /api/partner/v1/aml/screen/{address}
   Required header: X-API-Key
   Required scope: aml:read (operators grant it per key).
   Optional query: network (ethereum, bsc, polygon, avalanche, arbitrum, optimism, base) and depth (1-10, default 1).
   The report returns score (0-100) and a band of none/low/medium/high/severe that maps to a suggested action (allow, review, blockPendingReview, block or fileSar). Treat action as advice for your own policy, not an instruction.
   This runs a live multi-source lookup: set your HTTP timeout to at least 180 seconds and call it server-side. A 404 no_screening_data means the address has no history (often a clean, unused address). 429 rate_limited means slow down. 503 service_unavailable is transient, so retry.

9. Delete from partner views only when requested by the partner/user.
   DELETE /api/partner/v1/swaps/{id}
   Required header: X-API-Key
   Treat the swap as permanently removed from partner API and portal views after this call. It does not cancel a live swap.

Example curl calls:

```bash
curl https://b1exch.to/api/partner/v1/me \
  -H "X-API-Key: b1x_your_partner_key"

curl https://b1exch.to/api/partner/v1/currencies \
  -H "X-API-Key: b1x_your_partner_key"

curl -X POST https://b1exch.to/api/partner/v1/quote \
  -H "Content-Type: application/json" \
  -H "X-API-Key: b1x_your_partner_key" \
  -d '{
    "from": "BTC",
    "to": "LTC",
    "amount": 0.01,
    "destination": "ltc1q_customer_destination..."
  }'

curl -X POST https://b1exch.to/api/partner/v1/swaps \
  -H "Content-Type: application/json" \
  -H "X-API-Key: b1x_your_partner_key" \
  -d '{
    "from": "BTC",
    "to": "LTC",
    "amount": 0.01,
    "destination": "ltc1q_customer_destination...",
    "refund_address": "bc1q_customer_refund...",
    "reference": "order-123",
    "commission_address": "bc1q_partner_commission..."
  }'

curl https://b1exch.to/api/partner/v1/swaps/00000000-0000-0000-0000-000000000000 \
  -H "X-API-Key: b1x_your_partner_key"

curl "https://b1exch.to/api/partner/v1/aml/screen/0xADDRESS?network=ethereum" \
  -H "X-API-Key: b1x_your_partner_key"
```

Typical swap response shape:

```json
{
  "success": true,
  "swap": {
    "id": "246fb837-2dcb-4830-8e55-1491ba75be4a",
    "short_id": "246fb837",
    "status": "completed",
    "is_completed": true,
    "outcome": "success",
    "from_currency": "BTC",
    "to_currency": "LTC",
    "deposit_address": "bc1q_customer_deposit...",
    "destination_address": "ltc1q_customer_destination...",
    "refund_address": "bc1q_customer_refund...",
    "amount": 0.01,
    "deposit_amount": 0.01,
    "quoted_output": 1.234567,
    "min_output": 1.209876,
    "output_amount": 1.232100,
    "exchange_rate": 123.4567,
    "service_fee_percent": 1.0,
    "deposit_confirmations": 3,
    "output_confirmations": 1,
    "deposits": [
      {
        "txid": "8c63fc...",
        "currency": "BTC",
        "amount": 0.01,
        "confirmations": 3,
        "address": "bc1q_customer_deposit..."
      }
    ],
    "outputs": [
      {
        "txid": "98b7ad...",
        "currency": "LTC",
        "amount": 1.232100,
        "confirmations": 1,
        "address": "ltc1q_customer_destination..."
      }
    ],
    "reference": "order-123",
    "created_at": "2026-05-15T13:20:00Z",
    "expires_at": "2026-05-15T13:40:00Z",
    "completed_at": "2026-05-15T13:22:11Z",
    "commission_settings": {
      "percent": 2.0,
      "payout_method": "automatic_address",
      "payout_currency": "BTC",
      "payout_address": "bc1q_partner_commission..."
    },
    "commission": {
      "status": "paid",
      "payable": true,
      "payout_method": "automatic_address",
      "amount_usd": 1.27,
      "commission_percent": 2.0,
      "payout_currency": "BTC",
      "payout_address": "bc1q_partner_commission...",
      "payout_txid": "f7b2c1...",
      "created_at": "2026-05-15T13:22:30Z",
      "available_at": "2026-05-15T13:24:10Z",
      "paid_at": "2026-05-15T13:25:02Z"
    }
  }
}
```

Important behavior:
- GET /api/partner/v1/me returns partner, api_key, and limits metadata. Use api_key.scopes and limits.max_pending_swaps to validate setup.
- GET /api/partner/v1/currencies returns enabled currencies, decimal display precision, public minimum amounts, and partner API minimum USD values. Build forms from this instead of hardcoding enabled pairs or precision.
- POST /api/partner/v1/swaps is the live swap creation request. It calculates fresh pricing at creation time. Do not assume POST /quote locks price.
- Use reference as an idempotency key per API key. Same key + same reference + same details returns the existing swap. Same key + same reference + different details returns HTTP 409 with code duplicate_reference.
- refund_address is mandatory for API swap creation.
- commission_address must validate for the source/deposit currency. If omitted, payable commission is held in the partner balance for manual payout.
- Quote responses can include quote_id, from_currency, to_currency, amount, amount_usd, quoted_output, min_output, exchange_rate, service_fee_percent, service_fee_usd, exchange_fee_usd, network_fee, estimated_minutes, expires_in_seconds, binding=false, and note.
- Swap responses can include id, short_id, status, is_completed, outcome, from_currency, to_currency, deposit_address, destination_address, refund_address, amount, deposit_amount, quoted_output, min_output, output_amount, exchange_rate, service_fee_percent, deposit_confirmations, output_confirmations, deposits[], outputs[], refund, reference, created_at, expires_at, completed_at, commission_settings, and commission.
- Fields with no value are returned as null where applicable. deposits[] and outputs[] are always arrays.
- amount is the expected source amount from creation. deposit_amount is the accepted customer deposit amount when known. quoted_output is the creation-time expected output. min_output is the minimum acceptable output (slippage floor); when rate protection is selected it is returned separately as rate_protection_percent. output_amount is the customer payout amount when known.
- exchange_rate is the partner-facing quote rate. service_fee_percent is the partner-facing service fee percent.
- deposits[] is always an array and can contain multiple customer deposits. outputs[] is always an array and can contain one or more customer payout transactions.
- Each deposits[] and outputs[] item can include txid, currency, amount, confirmations, address, and vout when applicable.
- refund is included only when refund data exists and can include txid, amount, currency, address, reason, and refunded_at.
- commission_settings is included on swap responses and shows the commission percent and payout method captured when the swap was created.
- commission returns only the partner-facing result: status, payable flag, payable amount_usd, commission_percent, payout_method, payout_currency, payout_address, payout_txid when paid automatically, reason_code, message, created_at, available_at, and paid_at.
- Internal revenue, cost, margin, and profitability math are not exposed through the partner API.
- Transaction costs for automatic commission payouts are deducted from the partner share.
- There is currently no API endpoint for requesting manual commission payout. Manual payout requests are handled in the Partner Portal.
- The pending swap cap is per API key. If HTTP 429 returns code too_many_pending_swaps, stop creating swaps with that key until pending swaps complete or expire.
- GET /api/partner/v1/aml/screen has its own per-key rate limit. On breach it returns HTTP 429 with code rate_limited (distinct from too_many_pending_swaps); back off and retry.
- Status handling is deliberately simple. Use status plus is_completed instead of depending on internal backend stage names.
- While is_completed is false, keep polling and show the customer a normal in-progress state.
- Public status values are: waiting_for_deposit, processing, completed, expired, refunded, failed.
- When is_completed is true, stop polling and read outcome: success, expired, refunded, or failed.
- Commission status values are: pending, payable, payout_requested, paid, not_payable.
- Commission payout_method values are: partner_balance, automatic_address, manual_payout.
- Partner API application errors use JSON shape: success=false, code, error, and message.
- Always handle JSON errors for HTTP 400, 401, 403, 404, 409, 429, and 503. Invalid JSON can also produce framework validation details, so clients should still fall back to HTTP status and any title/message/error field.
- For 401, send a valid X-API-Key on the current request.
- For 403, the key may be missing a scope or the partner account/key may be suspended.
- For 404, the swap is not visible to this partner/key or the ID is wrong.
- For 409 duplicate_reference, do not create a new order under that reference; reconcile your local order state first.