Quickstart

Three steps: check your key, send a test webhook, then run one small real deposit.

You need an API key from ByteFederal. The examples read it from $API_KEY:

export API_KEY='your-api-key'

1. Check your key

GET /casino/integration/key describes the calling key and the casinos it can act on. It never returns secrets.

curl https://quinix.byteconnect.us/casino/integration/key \
  -H "X-API-Key: $API_KEY"

{
  "key": {
    "id": 42,
    "name": "Production key",
    "mode": "live",
    "scope": "admin",
    "expires_at": null
  },
  "affiliate": {
    "id": 5678,
    "name": "BurraPay"
  },
  "entity_scope": null,
  "entities": [
    {
      "id": 1234,
      "name": "Your Casino",
      "external_code": "your-casino-code",
      "status": "enabled",
      "webhook": {
        "url": "https://casino.example.com/webhooks/byteconnect",
        "signed": true,
        "source": "entity_override"
      }
    }
  ]
}

Check these fields:

Field	What to look for
`key.mode`	`test` while you integrate. See Live and test mode.
`key.scope`	Always `admin` here. A `terminal` key cannot call casino endpoints and gets `403` from this one.
`key.expires_at`	When the key stops working, in UTC. `null` means it does not expire.
`entity_scope`	`null` for an affiliate-wide key. Otherwise the one casino this key is locked to.
`entities[].id`	The `entity_id` you send when you create deposits for that casino.
`entities[].status`	Deposits can only be created for an `enabled` entity.
`entities[].webhook`	Where this casino's webhooks go. `null` means no webhook URL is configured. Ask ByteFederal to set one.
`entities[].webhook.signed`	`true` when deliveries carry an `X-Webhook-Signature` header. `false` means they are sent unsigned.
`entities[].webhook.source`	`entity_override`: the casino's own webhook URL. `api_key`: the webhook URL on an API key of your affiliate.

2. Send a test webhook

POST /casino/integration/test-webhook sends one sample event to the webhook URL configured for an entity. It is signed exactly like a real event.

curl -X POST https://quinix.byteconnect.us/casino/integration/test-webhook \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": 1234, "event": "ofac_complete"}'

Field	Type	Required	Description
`entity_id`	integer	yes	The entity whose webhook URL receives the event.
`event`	string	yes	Any event name from Webhook events.

The response reports what your endpoint answered:

{
  "event": "ofac_complete",
  "url": "https://casino.example.com/webhooks/byteconnect",
  "signed": true,
  "signature": "c9341a841acb4dde352659cf26b776427c4c42ba13321473b578bcb0b5364475",
  "delivered": true,
  "status_code": 200,
  "duration_ms": 184,
  "response_excerpt": "ok",
  "error": null,
  "payload": {
    "event": "ofac_complete",
    "deposit_id": 0,
    "transaction_id": 0,
    "entity_id": 1234,
    "entity_external_code": "your-casino-code",
    "gambler_ref": "sample-player-001",
    "ofac_result": "clear",
    "decision": "pending",
    "instant": false,
    "instant_downgraded": false,
    "acceptable": true,
    "crypto_amount": 0.00104359,
    "confirmed_crypto": 0.00104359,
    "currency": "BTC",
    "timestamp": 1790172000,
    "test": true
  }
}

Field	Description
`delivered`	`true` when your endpoint answered with a 2xx status.
`status_code`	Your endpoint's HTTP status. `null` when no response came back.
`error`	Why no response came back, for example a timeout or a refused connection. `null` otherwise.
`response_excerpt`	The first 500 characters of your endpoint's response body.
`signed`, `signature`	Whether the request was signed, and the `X-Webhook-Signature` value that was sent.
`payload`	The event that was sent.

What to know about test webhooks:

The request carries the header X-Webhook-Test: true, and the payload carries "test": true.
deposit_id and transaction_id are 0. No real deposit has id 0. Your endpoint should acknowledge the event without crediting anyone.
The signature covers the exact request body your endpoint received. Verify it against that raw body, not against payload re-serialized from this response. See Webhooks.
Nothing is stored and nothing is retried.
The request times out after 30 seconds. Redirects are not followed, so a 3xx answer counts as not delivered.
It works for an entity in any status, so you can test before a casino is enabled.
The webhook URL must be a public address. A URL that resolves to a private, loopback or link-local address is never contacted: the result has delivered: false and an error that says the address is non-public.
Each key can send 10 test webhooks per minute. Past that, the API returns 429 with a Retry-After header.

Errors specific to this endpoint:

Status	`detail`
400	`Unknown event '<event>'. See the webhook reference for valid event names.`
403	`API key is scoped to a different entity`
404	`Entity not found for this affiliate`
409	`No webhook URL is configured for this entity`

3. Run one small real deposit

Real crypto

There is no sandbox. This step moves real crypto on mainnet. Use a test-mode key and a small amount. A deposit created with a live key on a live entity is settled as real money once accepted.

Create the deposit. Use your own phone number as the player's.

curl -X POST https://quinix.byteconnect.us/casino/deposit_address \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": 1234,
    "currency": "BTC",
    "gambler_ref": "sample-player-001",
    "phone": "+15555550100",
    "amount": 10
  }'

The first request for a new gambler_ref does not create a deposit. It returns kyc_required, and ByteFederal texts a verification link to the phone number:

{
  "status": "kyc_required",
  "message": "Identity verification required. A verification link has been sent."
}

Complete the verification on your phone, then send the same request again. Until verification is complete, the request returns "status": "kyc_pending". See Player KYC.

Once the player is verified, the response has "status": "ok" and includes deposit_id, address, crypto_amount and expires_at. See Create a deposit for the full response.

Pay it. Send exactly crypto_amount to address. In a real integration you would show the player a 15-minute window; ByteFederal honors a payment until expires_at, 30 minutes after creation. See Expiry and late payments.

Follow it. Your webhook endpoint receives deposit.received, deposit.confirmed, ofac_complete and kyt_complete. You can also read the deposit at any time:

curl https://quinix.byteconnect.us/casino/deposit/$DEPOSIT_ID \
  -H "X-API-Key: $API_KEY"

See Deposit lifecycle and Read deposits.

Decide. When a webhook or a read shows "acceptable": true, accept the deposit:

curl -X POST https://quinix.byteconnect.us/casino/deposit/$DEPOSIT_ID/accept \
  -H "X-API-Key: $API_KEY"

Or return the crypto to an address you control. Your endpoint then receives deposit.accepted or deposit.returned. See Accept, return and freeze.

When this works end to end, read Testing and Going live.

1. Check your key​

2. Send a test webhook​

3. Run one small real deposit​

1. Check your key

2. Send a test webhook

3. Run one small real deposit