On-Chain Query Endpoints

Public endpoints intended to query the on-chain referral contracts. No authentication required.

Implementation status

The backend has no contract integration yet. The two routed endpoints below (user-rebate, referral-info) return placeholder "starter" values without reading the chain; claimed/:address and operator-status are not routed at all (404).

---

User On-Chain Rebate Info

Read the user's complete rebate status from the ReferralRebate contract.

GET /v1/referral/on-chain/user-rebate/:address

Placeholder implementation. Only referral_code is real data (the referral code owned by this address, looked up case-insensitively in the off-chain referral.codes table); every other field is a constant.

Path Parameters

Parameter	Type	Description
address	string	Wallet address. Not validated — any string is accepted and echoed back as-is

Response

{
  "address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
  "claimed_usd": "0",
  "nonce": 0,
  "referral_code": "",
  "referrer": "0x0000000000000000000000000000000000000000",
  "tier_level": 0,
  "tier_name": "Starter"
}

Field	Type	Description
address	string	The path parameter, echoed unchanged (not lowercased)
claimed_usd	string	Always "0" currently
nonce	uint64	Always 0 currently
referral_code	string	The referral code owned by this address (from the off-chain DB), or "" if none. Note: this is the address's own code, not the code it is bound to
referrer	string	Always the zero address currently
tier_level	uint8	Always 0 currently
tier_name	string	Always "Starter" currently

Error Codes

Errors are returned as a plain-text body, not JSON. No address validation is performed.

HTTP	Message	Description
500	(database error text)	Referral-code lookup failed

---

Trader On-Chain Referral Info

Read the trader's referral configuration (rebate BPS) from the ReferralRebate contract.

GET /v1/referral/on-chain/referral-info/:address

Placeholder implementation. Every field except the echoed address is a constant; nothing is read from the chain or the database.

Path Parameters

Parameter	Type	Description
address	string	Wallet address. Not validated — any string is accepted and echoed back as-is

Response

{
  "address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
  "code": "",
  "referrer": "0x0000000000000000000000000000000000000000",
  "total_rebate_bps": 0,
  "trader_discount_bps": 0,
  "affiliate_reward_bps": 0
}

Field	Type	Description
address	string	The path parameter, echoed unchanged
code	string	Always "" currently
referrer	string	Always the zero address currently
total_rebate_bps	uint16	Always 0 currently
trader_discount_bps	uint16	Always 0 currently
affiliate_reward_bps	uint16	Always 0 currently

Error Codes

This endpoint never returns an error (no validation, no I/O).

---

On-Chain Claimed Amount

Query the total amount a user has claimed on-chain.

GET /v1/referral/on-chain/claimed/:address

Status: Not yet implemented (空缺).

The route is not registered (requests return 404).

---

Operator Status

Check the backend signer address and its operator status in the contract.

GET /v1/referral/on-chain/operator-status

Status: Not yet implemented (空缺).

The route is not registered (requests return 404); the backend has no on-chain signer.

Code Examples

Python

import requests

BASE_URL = "https://api.rocky.exchange"
address = "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489"

# 1. User on-chain rebate info
resp = requests.get(f"{BASE_URL}/v1/referral/on-chain/user-rebate/{address}")
data = resp.json()
print(f"Tier: {data['tier_name']} (Level {data['tier_level']}), Claimed: {data['claimed_usd']}")

# 2. Trader referral info
resp = requests.get(f"{BASE_URL}/v1/referral/on-chain/referral-info/{address}")
data = resp.json()
print(f"Code: {data['code']}, Referrer: {data['referrer']}")
print(f"Rebate BPS: {data['total_rebate_bps']}, Discount: {data['trader_discount_bps']}, Reward: {data['affiliate_reward_bps']}")