Authentication

Token Format

The Agent Token uses a three-part structure, separated by .:

{agent_api_key}.{timestamp}.{signature}

Part	Type	Description	Example
agent_api_key	string	Your API Key	a9f3c28d7b1e4f90c2a1b3d4
timestamp	string	Current Unix timestamp (seconds)	1743055200
signature	string	HMAC-SHA256 signature (lowercase hex)	a1b2c3d4e5...

Signature Algorithm

signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) → lowercase hex

Generation Steps

1. Get current timestamp
   Unix timestamp in seconds, e.g. 1743055200

2. Concatenate the raw string

   raw_string = agent_api_key + "." + timestamp

3. Compute HMAC-SHA256 signature

   signature = HMAC-SHA256(raw_string, agent_api_secret)

   Convert to lowercase hex string

4. Assemble the Token

   token = agent_api_key + "." + timestamp + "." + signature

5. Set HTTP Header

   Authorization: Bearer {token}

Token Expiration

The timestamp in the Token must be within ±2 minutes of the server's current time, otherwise the request will be rejected. Ensure your server clock is accurate (NTP sync recommended).

Server-Side Verification Flow

Steps the server performs upon receiving a request:

1. Extract Token — Get Token from Authorization: Bearer {token} header
2. Split Token — Split by . into agent_api_key, timestamp, signature
3. Verify timestamp — Confirm timestamp is within 2 minutes of server time
4. Lookup secret — Use agent_api_key to retrieve agent_api_secret from database
5. Verify signature — Recompute HMAC-SHA256 with the secret and compare against signature

Mutual Signature Verification

To ensure API security, the authentication mechanism for mutual calls is defined as follows:

1. Agent calls VCT Platform (API Endpoints): The Agent must generate a Token according to the steps above and include it in the Authorization: Bearer {token} request header, which the VCT platform verifies.
2. VCT Platform calls Agent (Callback/Webhook Endpoints): When the VCT platform sends callback requests (such as balance query, deduction, settle, cancel, or push bet data) to the Agent, no Authorization request header is sent. Instead, the Agent system only needs to verify the parameters signature inside the request body:
   • For standard callbacks (/balance, /bet, /settle, /cancel): signature = HMAC-SHA256(username + "." + timestamp, agent_api_secret)
   • For wager data push (/bet-push): signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) The Agent system should verify that the sign field in the request body matches the signature calculated above.