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

When you create the key, select every scope this integration needs. The default scope set covers wallet and trading reads and writes but does not include webhooks:manage, webhooks:view, or wallets:withdraw. Step 1 below needs webhooks:manage, and step 8 needs wallets:withdraw. Scopes cannot be added to an existing key, so a key created without them must be replaced. 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.partial",
      "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"

The response carries balances, withdrawable, and credit. Use withdrawable when deciding how much can be withdrawn right now. Use balances[].available for other spendable-balance decisions such as order sizing, and balances[].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 returns order_id, status: "pending", and created_at; it means the request was accepted for processing, not that the order is filled. Idempotency-Key must be a UUID. Set client_order_id in the body if you need to find the order again from your own records.

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, withdrawal.partial, 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