Quickstart

You will go from a sandbox API key to a settled deposit and a settled payout, tracked by webhook. Nothing here moves real money.

Time: about 20 minutes. You need: curl or an HTTP client, and a publicly reachable URL for webhooks (optional — you can poll instead).

📘
Base URLs
Sandbox is https://sandbox-api.omicloud.io. Production is https://api.omicloud.io. A sandbox key does not work in production and vice versa. Every example below uses the sandbox.

Step 1 — Get a sandbox key

In the OmiCloud console go to API keys → Create key, choose the test environment, and copy the key. It starts with omi_test_ and is shown once.

Every request carries it as a bearer token:

Authorization: Bearer omi_test_…
Content-Type: application/json
Omi-Version: 2026-09-01

Step 2 — Register a webhook endpoint (optional)

Webhooks tell you when a transaction changes state. You can skip this and poll GET /v1/transactions/{reference} instead.

curl -X POST https://sandbox-api.omicloud.io/v1/webhook-endpoints \
  -H "Authorization: Bearer omi_test_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/omicloud","description":"quickstart"}'

{
  "id": "whe_01j6ya2c8r5t",
  "url": "https://example.com/hooks/omicloud",
  "events": [],
  "status": "active",
  "secret": "whsec_9Qx2v7LmT4pRkZ1nHc8bWa3eYf6sUd0J",
  "secretPrefix": "whsec_9Qx2",
  "createdAt": "2026-09-02T10:00:00Z"
}

Store secret now — it is not shown again. For local testing use a tunnel such as ngrok. See Webhook authentication to verify deliveries.

Step 3 — See what you can execute

curl "https://sandbox-api.omicloud.io/v1/routes?direction=deposit&currency=USDT" \
  -H "Authorization: Bearer omi_test_…"

{
  "data": [
    {
      "gateway": "dce",
      "direction": "deposit",
      "paymentType": "crypto",
      "paymentMethod": "USDT_TRC20",
      "currency": "USDT",
      "network": "TRX",
      "limits": { "min": "10", "max": "50000" },
      "feeBps": 80,
      "settlement": "on_chain_confirmation"
    }
  ]
}

Validate the end user's amount against limits before you go further.

Step 4 — Deposit: create a session

curl -X POST https://sandbox-api.omicloud.io/v1/sessions \
  -H "Authorization: Bearer omi_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-dep-1" \
  -d '{
    "amount": "100",
    "currency": "USDT",
    "network": "TRX",
    "endUserId": "quickstart-user",
    "operatorReference": "quickstart-dep-1",
    "redirectUrl": "https://example.com/return"
  }'

{
  "id": "ses_01j6y9f0k3qz",
  "transaction": "txn_8f3a1c9e02b4",
  "state": "processing",
  "gateway": "dce",
  "url": "https://pay.dcepay.dev/s/eyJhbGciOi…",
  "expiresAt": "2026-09-02T10:20:00Z",
  "deposit": {
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "network": "TRX",
    "currency": "USDT",
    "amount": "100"
  }
}

Open url. In the sandbox, the gateway's hosted page lets you simulate a completed deposit without sending real crypto — see Sandbox testing for the exact controls.

Step 5 — Track it

If you registered a webhook, you will receive transaction.settled:

{
  "id": "evt_01j6ybq7m2vx",
  "type": "transaction.settled",
  "createdAt": "2026-09-02T10:18:41Z",
  "version": "2026-09-01",
  "operatorId": "op_…",
  "endpointId": "whe_01j6ya2c8r5t",
  "data": {
    "transaction": "txn_8f3a1c9e02b4",
    "operatorReference": "quickstart-dep-1",
    "state": "settled",
    "previousState": "processing",
    "gateway": "dce",
    "direction": "deposit",
    "amount": "100",
    "currency": "USDT"
  }
}

Either way, fetch the transaction — it is the source of truth:

curl https://sandbox-api.omicloud.io/v1/transactions/txn_8f3a1c9e02b4 \
  -H "Authorization: Bearer omi_test_…"

{
  "reference": "txn_8f3a1c9e02b4",
  "operatorReference": "quickstart-dep-1",
  "direction": "deposit",
  "state": "settled",
  "gatewayState": "confirmed",
  "gateway": "dce",
  "amount": "100",
  "currency": "USDT",
  "network": "TRX",
  "fees": { "gateway": "0.80", "network": "0", "total": "0.80" },
  "netAmount": "99.20",
  "crypto": { "txHash": "0x553d…9ba0", "address": "TQn9…bLSE" },
  "events": [
    { "from": null, "to": "submitted", "source": "operator_submission", "at": "…" },
    { "from": "submitted", "to": "processing", "source": "system", "at": "…" },
    { "from": "processing", "to": "settled", "source": "webhook", "at": "…" }
  ]
}

Step 6 — Payout

Payouts require an Idempotency-Key; a retry without one is refused because it could pay twice.

curl -X POST https://sandbox-api.omicloud.io/v1/payouts \
  -H "Authorization: Bearer omi_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-wd-1" \
  -d '{
    "amount": "25",
    "currency": "USDT",
    "network": "TRX",
    "destination": { "type": "crypto_address", "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" },
    "endUserId": "quickstart-user",
    "operatorReference": "quickstart-wd-1"
  }'

{ "transaction": "txn_2b7d9e4f11a0", "state": "processing", "gateway": "dce", "gatewayReference": "wd_7f1c2a" }

Track it exactly as in step 5. When it settles, crypto.txHash is the on-chain transfer.

You are done

You have run both directions against the sandbox. Next:

Accepting deposits — sessions in depth: routing, expiry, rendering your own QR.
Sending payouts — destinations, idempotency, failure handling.
Webhook events — every event and how to build a receiver that survives retries and reordering.