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

# Get apiv1referrals



## OpenAPI

````yaml /api-reference/stellar-aggregator-openapi.json get /api/v1/referrals/{id}
openapi: 3.1.0
info:
  title: Stellar DEX Aggregator API
  description: >-
    Soroban DEX aggregator and routing engine for Stellar. Bounded multi-DEX
    routing across Soroban venues: Soroswap, Aquarius, Phoenix, Sushi, and
    Comet.


    ## Features

    - Forward & reverse quotes (given input → output, or target output → input)

    - Multi-path split allocation across pools to minimize price impact

    - Optional server-side simulated `TransactionEnvelope` requiring account
    sequence and signature

    - Auto-fallback when the on-chain budget rejects the requested config

    - Echoes USD value + protocol/referral fees
  license:
    name: MIT
    identifier: MIT
  version: 0.1.0
servers:
  - url: https://stellar-swap.xoxno.com
    description: Public deployment; verify network with /api/v1/config
security: []
tags:
  - name: Discovery
    description: Deployment, pools and referral fee policy
  - name: Health
    description: Liveness and readiness probes
  - name: Tokens
    description: Routable token catalog
  - name: Quote
    description: Routing, quoting, and transaction-envelope construction
paths:
  /api/v1/referrals/{id}:
    get:
      tags:
        - Discovery
      operationId: referral_handler
      parameters:
        - name: id
          in: path
          description: Unsigned u32 decimal referral ID; 0 means no referral
          required: true
          schema:
            type: string
          example: '0'
      responses:
        '200':
          description: >-
            Active referral fee, from the quote cache (up to 60 seconds old);
            cache misses query RPC
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralResponse'
        '400':
          description: Invalid referral identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryError'
        '502':
          description: Referral RPC lookup failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryError'
        '503':
          description: Router is not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryError'
components:
  schemas:
    ReferralResponse:
      type: object
      required:
        - id
        - active
        - staticFeeBps
        - feePolicy
        - whitelistedTokens
      properties:
        active:
          type: boolean
          description: >-
            An active referral was found. False includes missing and inactive
            IDs;

            ID zero is the no-referral sentinel, not a registered referral.
        feePolicy:
          type: string
          description: Input unless the output is whitelisted and the input is not.
        id:
          type: string
          description: Referral identifier as a decimal string.
        referralFeeBps:
          type:
            - integer
            - 'null'
          format: int32
          description: Active referral fee; null when no active referral was found.
          minimum: 0
        staticFeeBps:
          type: integer
          format: int32
          description: >-
            Cached router admin fee, charged only with an active nonzero
            referral.
          minimum: 0
        totalFeeBps:
          type:
            - integer
            - 'null'
          format: int32
          description: Zero for id zero; null for missing/inactive referrals.
          minimum: 0
        whitelistedTokens:
          type: array
          items:
            type: string
          description: Cached token whitelist used by the quote fee calculation.
    DiscoveryError:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
        error:
          type: string
          description: Human-readable diagnostic; use code for programmatic handling.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.