Bind Referral Code

Bind the current user (Trader) to a referrer via their referral code. A user can be bound to only one referrer at a time: rebinding is not supported — an already-bound user receives 409 and must first call Unbind.

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

Request Body

{
  "code": "4DDDC2D4",
  "signature": "0x...",
  "timestamp": 1772010600
}

Field	Type	Required	Description
code	string	Yes	The referral code to bind to. Matched exactly (case-sensitive) against existing codes; no format normalisation is applied
signature	string	No	EIP-712 signature — accepted for forward compatibility, not verified
timestamp	uint64	No	Unix timestamp (seconds) — accepted for forward compatibility, not verified

EIP-712 Signature

Not verified by the backend at present; retained for forward compatibility. Only code is read from the body.

TypeHash: BindReferralCode(address wallet,string code,uint256 timestamp)

{
  "primaryType": "BindReferralCode",
  "types": {
    "BindReferralCode": [
      { "name": "wallet", "type": "address" },
      { "name": "code", "type": "string" },
      { "name": "timestamp", "type": "uint256" }
    ]
  },
  "message": {
    "wallet": "0x<your_address>",
    "code": "4DDDC2D4",
    "timestamp": 1772010600
  }
}

Response

{
  "success": true,
  "referrer_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
  "referrer_code": "4DDDC2D4"
}

Field	Type	Description
success	bool	Whether binding succeeded
referrer_address	string | null	The referrer's wallet address (null if the referrer's session had no wallet address)
referrer_code	string	The referral code that was bound

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	cannot bind to your own code	Cannot use your own referral code
401	missing bearer token / invalid session	Missing, expired or revoked session token
404	referral code not found	Referral code does not exist
409	already bound to a referrer	User is already bound; unbind first
422	(JSON deserialisation error)	code missing from the body
500	(database error text)	Server error

Code Examples

Python

import time, requests
from eth_account import Account
from eth_account.messages import encode_typed_data

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

wallet = Account.from_key(PRIVATE_KEY)
timestamp = int(time.time())
code = "4DDDC2D4"

typed_data = {
    "types": {
        "EIP712Domain": [
            {"name": "name", "type": "string"},
            {"name": "version", "type": "string"},
            {"name": "chainId", "type": "uint256"},
        ],
        "BindReferralCode": [
            {"name": "wallet", "type": "address"},
            {"name": "code", "type": "string"},
            {"name": "timestamp", "type": "uint256"},
        ],
    },
    "primaryType": "BindReferralCode",
    "domain": {"name": "Rocky", "version": "1", "chainId": 43114},
    "message": {"wallet": wallet.address, "code": code, "timestamp": timestamp},
}

signable = encode_typed_data(full_message=typed_data)
signed = wallet.sign_message(signable)

resp = requests.post(
    f"{BASE_URL}/v1/referral/bind",
    headers={"Authorization": f"Bearer {JWT_TOKEN}", "Content-Type": "application/json"},
    json={"code": code, "signature": signed.signature.hex(), "timestamp": timestamp},
)
print(resp.json())
# {"success": true, "referrer_address": "0x29f7...5489", "referrer_code": "4DDDC2D4"}