Integration

Build on ClashX

Your front end, your players, your wallet. ClashX supplies the games and settles the money behind it. Everything below is the /partner/v1 contract.

The redirect contract

https://{casino-host}/launch?token={launch_token}

Mint a token with POST /partner/v1/sessions, redirect the player there, and stop. ClashX will host the exchange page, but it is not deployed yet and /launch returns 404 today, so build the exchange on your side until it ships. The redirect URL and the token contract will not change.

ClashX Partner API →

The full reference: endpoints, scopes, the transfer wallet, the match feed, settlement callbacks, and what each refusal means.

Build a ClashX Integration →

The same material as an implementation sequence, with real curl examples and a verification checklist. Copy it straight into your AI assistant.

The six calls, in order

#CallWhy
1GET /partner/v1/pingConfirms the key works and reports the scopes you actually hold. The fastest way to diagnose a 403 later.
2POST /partner/v1/sessionsGet-or-create the player from your external_ref, and mint a launch token.
3POST /partner/v1/wallet/creditMove value into the player's balance before they play.
4Redirect the browserhttps://{casino-host}/launch?token={launch_token}, ⚠ the hosted page is not deployed yet (/launch 404s); build the exchange on your side until it ships.
5Receive match.settledSigned callbacks to your endpoint. Return 2xx as soon as you have durably accepted.
6GET /partner/v1/matchesPoll as the backstop. Same query as the push feed, so the two cannot disagree.

Authenticate every /partner/v1 call with X-Api-Key, not Authorization: Bearer.

curl -s https://api.clashx.example/partner/v1/ping \
  -H "X-Api-Key: $CLASHX_KEY"

Four things that will bite you

  1. A rejected transfer returns HTTP 200. Insufficient balance is a business outcome, not an error. Branch on kind, never on the status code.

  2. applied: false means replay, not failure. Retry a wallet call with the same transfer_ref, never a new one.

  3. Errors carry no machine-readable code. Match on HTTP status; do not parse messages.

  4. A launch token lives 60 seconds and is single-use. Mint it at the moment of the click, not when the page renders.

Your reconciliation has five terms, not four

credited − staked + won + refunded − debited  ==  balance

refund_cents is a separate field from payout_cents, and it is non-zero on a failed start, a forfeit, a draw, or an abandoned match. Omit it and every refunded match reports a false discrepancy.