---
title: "Claim a referral code"
method: POST
path: "/v1/referral/claim"
tags: ["Referral"]
---

# Claim a referral code

`POST /v1/referral/claim`

## Request

- Base URL: `https://api.ethereal.trade`
- URL: `https://api.ethereal.trade/v1/referral/claim`
- Auth: none declared
- TypeScript: <https://skmtc.dev/ethereal/apis/ethereal-exchange-api/docs/v1/referral/claim/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- ClaimReferralCodeDto
  - `data` ClaimReferralCodeDtoData, required
    - `code` string, required: The referral code to claim
    - `intent` 0 | 1 | 2 | 3, required: Intent of the message (action to be taken)
    - `sender` string, hex, required: Account address that produced the authorizing signature
    - `signedAt` integer, required: Message signedAt current timestamp (seconds since Unix Epoch)
  - `signature` string, hex, required: Hex-encoded EIP-712 signature authorizing this request

## Response `201`

- ReferralDto
  - `code` string: The referee's referral code to be shared and claimed by others (undefined if not activated)
  - `codeUsageRemaining` integer, required: Number of remaining times the referral code can be claimed
  - `createdAt` integer, required: Timestamp of when this referral was activated (ms since Unix Epoch)
  - `id` string, uuid, required: Id representing the referral
  - `referee` string, hex, required: Address of the referee (non-checksummed)
  - `refereeTotalPoints` string, decimal, required: Total points (excl. referral points) earned by the referee since referee claimed the code (precision: 9)
  - `referrer` string, hex: Address of the referrer (non-checksummed; undefined if not set)

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `413`: Payload Too Large
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-08-25** `63e8937ff6f7`: 1 info
  - added the non-success response with the status `413`
- **2026-06-07** `dc14c1586dfa`: 6 breaking, 13 info
  - added `#/components/schemas/EIP712AuthIntent` to the `data/intent` request property `allOf` list
  - removed the enum value `0.00` of the request property `data/intent`
  - removed the enum value `1.00` of the request property `data/intent`
  - removed the enum value `2.00` of the request property `data/intent`
  - …15 more
- **2026-03-15** `b29881d08c78`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ethereal/apis/ethereal-exchange-api/changes/v1/referral/claim/post.md)

---

[API](https://skmtc.dev/ethereal/apis/ethereal-exchange-api.md) - [All operations](https://skmtc.dev/ethereal/apis/ethereal-exchange-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ethereal/apis/ethereal-exchange-api/revisions/63e8937ff6f7?raw)