Quickstart

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.

0. Configure Your Environment

Create a staging API key in the Stabyl staging app, then configure your server-side environment:

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. Create your HTTPS receiver before initiating asynchronous activity:

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 for signature verification and durable deduplication.

2. List supported chains

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

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

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

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:

curl "$STABYL_BASE_URL/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491" \
  -H "X-Api-Key: $STABYL_API_KEY"

7. Reconcile wallet activity

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 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.

Get Started

Wallets

Exchange

Webhooks

WebSocket

0. Configure Your Environment

2. List supported chains

3. Request a Tron deposit address

4. Read balances

5. Create an order

6. Receive order status changes

7. Reconcile wallet activity

8. Submit a withdrawal

​0. Configure Your Environment

​1. Subscribe to webhooks

​2. List supported chains

​3. Request a Tron deposit address

​4. Read balances

​5. Create an order

​6. Receive order status changes

​7. Reconcile wallet activity

​8. Submit a withdrawal

0. Configure Your Environment

1. Subscribe to webhooks

2. List supported chains

3. Request a Tron deposit address

4. Read balances

5. Create an order

6. Receive order status changes

7. Reconcile wallet activity

8. Submit a withdrawal