Claim Earnings

Off-Chain Claim

Transfer the user's entire pending off-chain referral earnings to their USDT account balance. This is instant and requires no on-chain transaction; partial claims are not supported.

POST /v1/referral/claim
Authorization: Bearer <token>
Content-Type: application/json

Request Body

None required — the backend ignores the request body (an empty body or {} are both accepted).

Response

{
  "success": true,
  "amount": "45.00",
  "tx_hash": null
}

Field	Type	Description
success	bool	Always true on success
amount	string	Full pending amount credited to the USDT account balance (decimal string, 2 dp)
tx_hash	null	Always null for off-chain settlement

On success the pending balance is reset to 0, a referral.claims row is recorded, and a claim entry is appended to Referral Logs.

Error Codes

Error format. Referral endpoints return errors as a plain-text body (text/plain) containing the message shown in the Message column, not a JSON object. A missing or invalid Authorization: Bearer session token returns 401 with missing bearer token / invalid session.

HTTP	Message	Description
400	NO_PENDING_EARNINGS: no pending earnings to claim	Pending balance is 0
400	BELOW_MINIMUM: pending amount is below the 10 USDT minimum	Pending balance is below the 10 USDT minimum
401	missing bearer token / invalid session	Missing, expired or revoked session token
500	(database error text)	Server error

---

On-Chain Claim Signature

Generate an EIP-712 signature for the user to call claimRebate on the ReferralRebate smart contract.

POST /v1/referral/on-chain/claim-signature
Authorization: Bearer <token>
Content-Type: application/json

Status: Not yet implemented (空缺).

The route is not registered (requests return 404); there is no on-chain rebate ledger or backend signer yet. Use the off-chain claim above.

Code Examples

Python — Off-Chain Claim

import requests

BASE_URL = "https://api.rocky.exchange"
JWT_TOKEN = "your_jwt_token"

resp = requests.post(
    f"{BASE_URL}/v1/referral/claim",
    headers={"Authorization": f"Bearer {JWT_TOKEN}", "Content-Type": "application/json"},
    json={},
)
data = resp.json()
print(f"Claimed: {data['amount']} USDT, success={data['success']}")