Player KYC

A player must verify their identity with ByteFederal before their first deposit. The check happens inside POST /casino/deposit_address. You do not call a separate KYC endpoint.

How it works

Every create call checks the player first. The player is identified by the pair entity_id + gambler_ref.

• Verified player: the deposit is created. The response has "status": "ok".
• New player: no deposit is created. ByteFederal texts the player a verification link. The response has "status": "kyc_required".
• Player who has not finished verifying: no deposit is created. The response has "status": "kyc_pending".

Verification is per casino. The same person at two of your casinos, or under two different gambler_ref values, is two separate players. Keep gambler_ref stable for a player.

If the phone number already belongs to a verified ByteFederal customer, the player does not repeat full verification. They receive a confirmation link instead, and confirm that the existing account is theirs.

Request

phone is required on every create call, including for verified players. Send it in E.164 format (+ and country code). A number without a country code is read as a US number.

email is optional. If you send it on the player's first create call, ByteFederal also emails the verification link to that address.

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": "+15555550123",
    "email": "[email protected]",
    "amount": 100
  }'

See Create a deposit for every request field.

Responses

All three outcomes return HTTP 200. Branch on status, never on message. The message text varies.

kyc_required

Returned on the first create call for a new gambler_ref. A link has been sent to the player.

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

When the phone number matches an existing verified ByteFederal customer:

{
  "status": "kyc_required",
  "message": "We found an existing account. A confirmation link has been sent."
}

kyc_pending

Returned on later create calls while the player has not finished verifying.

{
  "status": "kyc_pending",
  "message": "Identity verification is pending. Please complete verification to proceed."
}

If this call re-sent the link and the phone number matches an existing verified customer, the message is:

{
  "status": "kyc_pending",
  "message": "We found an existing account. A confirmation link has been sent."
}

ok

The player is verified and the deposit was created. The response carries the deposit address and amounts. See Create a deposit.

No deposit, address or webhook exists for a kyc_required or kyc_pending response. There is nothing to cancel.

What the player receives

ByteFederal sends the link by SMS to the phone number in the request. If an email address is on file for the player, the same link is also emailed.

For a new player, the SMS reads:

Byte Federal: To complete your cryptocurrency transaction, identity verification is required. Please verify your identity here: <link>

Reply STOP to unsubscribe.

For a phone number that matches an existing verified customer, the SMS names the account holder:

Byte Federal: We found an existing account for <First Last>. To complete your cryptocurrency transaction, please confirm your identity here: <link>

Reply STOP to unsubscribe.

A link is valid for 24 hours.

What to show the player

On kyc_required or kyc_pending:

1. Tell the player that ByteFederal has texted a verification link to their phone number, and to their email if they gave one.
2. Ask them to open the most recent message and complete verification.
3. Give them a way to continue when they are done, for example an "I've verified" button. That button makes the create call again.

The kyc_required response does not guarantee the text was delivered. Sending happens in the background after the response. If the player says no message arrived, check the phone number you sent.

Retrying after verification

ByteFederal does not send a webhook when a player finishes KYC. To find out, make the same create call again with the same entity_id and gambler_ref. When the player is verified, it returns "status": "ok" and a new deposit.

A create call for an unverified player re-sends the link when the last link was sent more than 10 minutes ago. Each re-send starts a new verification session and replaces the previous link.

warning

Only the most recent link works. If a player completes verification through an older link after a newer one was sent, their verification is not recorded for your casino. They must use the newest link.

Do not poll the create endpoint while the player is verifying. Retry when the player tells you they are done. Polling re-sends the link every 10 minutes and invalidates the link the player may be using.

When verification does not complete

Situation	What you see	What to do
The player has not finished verifying.	kyc_pending	Ask the player to finish, using the newest link.
The link expired after 24 hours.	kyc_pending	Call create again. A new link is sent, since more than 10 minutes have passed.
The player's ByteFederal identity was deactivated after verification.	kyc_pending on every call. No new link is sent.	Contact ByteFederal.
ByteFederal's identity service is unavailable.	HTTP 503 with "detail": "Identity verification service unavailable"	Retry later.

Endpoints you do not call

The API reference also lists POST /casino/kyc/confirm and POST /casino/web-kyc/callback. ByteFederal's own verification pages use them to record a completed verification. Partners never call them.