---
title: "Bind Code"
method: POST
path: "/api/referrals/bind"
tags: ["Referrals"]
---

# Bind Code

`POST /api/referrals/bind`

## Request

- Base URL: `https://backend-global.gains.trade`
- URL: `https://backend-global.gains.trade/api/referrals/bind`
- Auth: none declared
- TypeScript: <https://skmtc.dev/gains/apis/gains-network-backend-api/docs/api/referrals/bind/post.ts> (a function with typed inputs; its response is checked against the schema)

Attaches a referrer to a wallet from an EIP-712 `BindCode` signature. Only accepted while the wallet has never traded on a covered chain; afterwards it returns 409 AlreadyTraded permanently. Also available over GET, as for Register Code.

## Request body

- SignedReferralWrite
  - `message` object, required: The signed struct plus a `kind` discriminator. `kind` is transport metadata and is not part of the EIP-712 struct.
    - `kind` 'register_code' | 'bind_code', required
    - `owner` string: Subject for register_code. Must be the signer.
    - `referee` string: Subject for bind_code. Must be the signer.
    - `code` string, required: Must match ^[a-z0-9_]{1,31}$. Normalize before signing; the server rejects rather than normalizing.
    - `nonce` integer, required: Strictly increasing per signer, shared across both kinds. Date.now() in milliseconds works.
    - `validUntil` integer, required: Unix seconds. Must be in the future and at most 900 seconds ahead.
  - `signature` string, required: 65-byte ECDSA signature, 0x-prefixed hex. EIP-1271 is not supported.

## Response `201`

Applied

- object
  - `result` object
    - `signer` string

## Other responses

- `400`: Malformed message, or signature expired
- `401`: Recovered signer is not authorized for the subject
- `403`: Origin not allowed
- `409`: AlreadyTraded, AlreadyBound, CodeUnknown, SelfReferral, Cycle or BadNonce
- `429`: Rate limited
- `503`: Signed referral writes are disabled, or trade history unavailable

## Changes

- **2026-11-03** `4b415b6ff9d6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gains/apis/gains-network-backend-api/changes/api/referrals/bind/post.md)

---

[API](https://skmtc.dev/gains/apis/gains-network-backend-api.md) - [All operations](https://skmtc.dev/gains/apis/gains-network-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gains/apis/gains-network-backend-api/revisions/4b415b6ff9d6?raw)