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

# Quickstart

> Make the first calls for wallet discovery, balances, market data, orders, and reconciliation.

Use staging while building automation. Keep `X-Api-Key` in a backend service, job runner, or secure internal tool. Never expose it in browser, mobile, desktop, or user-controlled code.

```mermaid theme={null}
sequenceDiagram
    participant App as Your Service
    participant API as Stabyl API

    App->>API: POST /partner/webhooks
    App->>API: GET /partner/wallets/chains
    App->>API: GET /partner/wallets/crypto/address?chain=tron
    App->>API: GET /partner/wallets/balances/overview
    App->>API: GET /partner/exchange/markets
    App->>API: POST /partner/exchange/orders
    App->>API: POST signed /partner/wallets/withdrawals
    API-->>App: Signed webhook events
    App->>API: Periodic REST reconciliation
```

## 0. Configure Your Environment

Create a staging API key in the
[Stabyl staging app](https://app-staging.stabyl.com), then configure your
server-side environment:

```bash theme={null}
export STABYL_BASE_URL="https://api-staging.stabyl.com/v1"
export STABYL_API_KEY="sb_test_..."
```

Use staging keys against staging URLs. Production API access requires completed
KYB and an explicit invitation from Stabyl; staging access does not grant
production access. After invitation, use production credentials only against
the production URL. Treat cross-environment authentication failures as
configuration errors, not transient failures.

## 1. Subscribe to webhooks

Create your HTTPS receiver before initiating asynchronous activity:

```bash theme={null}
curl "$STABYL_BASE_URL/partner/webhooks" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "url": "https://partner.example.com/stabyl/events",
    "description": "Stabyl event receiver",
    "enabled": true,
    "event_types": [
      "deposit.action_required",
      "deposit.success",
      "deposit.failed",
      "withdrawal.success",
      "withdrawal.failed",
      "exchange.accepted",
      "exchange.filled",
      "exchange.replaced",
      "exchange.cancelled",
      "exchange.rejected"
    ]
  }'
```

Store the returned `whsec_...` secret immediately; it is shown only once. See
[Webhooks](/docs/webhooks) for signature verification and durable deduplication.

## 2. List supported chains

```bash theme={null}
curl "$STABYL_BASE_URL/partner/wallets/chains"
```

This route is public. Use it to decide which chain options to show before you request a crypto deposit address.

## 3. Request a Tron deposit address

```bash theme={null}
curl "$STABYL_BASE_URL/partner/wallets/crypto/address?chain=tron" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

Addresses are created only when requested for a chain. Store the returned `chain`, optional `slug`, `address`, and `memo` exactly as returned.

## 4. Read balances

```bash theme={null}
curl "$STABYL_BASE_URL/partner/wallets/balances/overview" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

Use `available` for actions that require spendable balance. Use `locked` to explain funds committed to pending activity.

## 5. Create an order

```bash theme={null}
curl "$STABYL_BASE_URL/partner/exchange/orders" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50221" \
  -d '{
    "pair_id": "USD/NGN",
    "side": "buy",
    "order_type": "limit",
    "price": "1520.00",
    "quantity": "100.00"
  }'
```

Order creation is asynchronous. A successful response means the request was accepted for processing, not that the order is filled.

## 6. Receive order status changes

Use exchange webhooks for durable lifecycle events. Use private WebSocket topics
when your application also needs low-latency order and fill streams. REST order
detail remains available for startup recovery, missed-event repair, and operator
lookups:

```bash theme={null}
curl "$STABYL_BASE_URL/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

## 7. Reconcile wallet activity

```bash theme={null}
curl "$STABYL_BASE_URL/partner/wallets/transactions?limit=50" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

Store the returned cursor and continue paging until `next_cursor` is `null`.
Run this as periodic reconciliation and after webhook downtime rather than as a
per-transaction polling loop. Reconciliation jobs should be restartable and
should tolerate records arriving after confirmation or settlement updates.

## 8. Submit a withdrawal

Follow [Withdrawal examples](/docs/withdrawal-examples) to quote, sign, and
submit NGN or stablecoin withdrawals. Persist the returned transaction ID and
complete the workflow from `withdrawal.success` or `withdrawal.failed`; use the
transaction detail route only for targeted recovery and reconciliation.