---
title: "Register Code"
method: POST
path: "/api/referrals/code"
tags: ["Referrals"]
---

# Register Code

`POST /api/referrals/code`

## Request

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

Registers a referral code from an EIP-712 `RegisterCode` signature. No API key; the signature is the sole authority. The same operation is available over GET with the message base64url-encoded in a `message` query parameter, for clients behind an edge that blocks POST.

## 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`: CodeTaken, OwnerHasCode, CodeReserved or BadNonce
- `429`: Rate limited
- `503`: Signed referral writes are disabled

## Changes

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

[Operation history](https://skmtc.dev/gains/apis/gains-network-backend-api/changes/api/referrals/code/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)