> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlayer.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Create protocol referral code

> 
    Create a custom protocol-level referral code for users who have traded over $10,000.
    The code can be shared with others to establish referral relationships.

    Requirements:
    - User must have traded at least $10,000 in total volume
    - Code must be 4-20 alphanumeric characters
    - User can only have one active referral code

    Returns the referral code (frontend constructs the full URL as: ${APP_URL}/join/{code})
  



## OpenAPI

````yaml post /create-referral-code
openapi: 3.0.3
info:
  title: Token Layer API
  version: 1.0.0
  description: |2-

          Token Layer is an omnichain token trading platform where users can create and trade tokens across multiple chains.

          This API provides comprehensive access to token operations, trading, earnings,
          blockchain transactions, and portfolio management.

          ## Base URL
          All endpoints are accessed via: `https://api.tokenlayer.network/{endpoint}`

          ## Authentication
          Most endpoints require authentication using an JWT token or API key passed as a Bearer token in the Authorization header.

          ## Rate Limiting
          API calls are rate limited per user. Please implement appropriate backoff strategies.
        
  contact:
    name: Token Layer API Support
    url: https://app.tokenlayer.network
servers:
  - url: https://api.tokenlayer.network/functions/v1
    description: Production server
  - url: https://api.tokenlayer.network/functions/v1
    description: Staging server
security: []
tags:
  - name: Tokens
    description: Token creation, browsing, search, trading, and price operations
  - name: Transactions
    description: Blockchain transactions (send, tip, ownership checks)
paths:
  /create-referral-code:
    post:
      tags:
        - Referrals
      summary: Create protocol referral code
      description: |2-

            Create a custom protocol-level referral code for users who have traded over $10,000.
            The code can be shared with others to establish referral relationships.

            Requirements:
            - User must have traded at least $10,000 in total volume
            - Code must be 4-20 alphanumeric characters
            - User can only have one active referral code

            Returns the referral code (frontend constructs the full URL as: ${APP_URL}/join/{code})
          
      operationId: createReferralCode
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReferralCodeRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReferralCodeResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Response 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateReferralCodeRequest:
      type: object
      properties:
        code:
          type: string
          pattern: ^[a-zA-Z0-9]{4,20}$
          description: Custom referral code (4-20 alphanumeric characters)
          example: ALICE2025
        network_mode:
          type: string
          enum:
            - testnet
            - mainnet
            - both
          default: mainnet
          description: Network mode for this referral code
          example: mainnet
      required:
        - code
    CreateReferralCodeResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        referral_code:
          type: string
          description: >-
            The created referral code (lowercase). Frontend should construct
            full URL as ${APP_URL}/join/${code}
          example: alice2025
        created_at:
          type: string
          description: Timestamp when the code was created
          example: '2025-01-06T12:00:00Z'
      required:
        - success
        - referral_code
        - created_at
    Error:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
      required:
        - success
        - error
      description: Error response
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token or API key

````