Bridge Rewards API

openapi: 3.0.2
info:
  title: Bridge API Keys Rewards API
  description: APIs to move into, out of, and between any form of a dollar
  version: '1'
servers:
- url: https://api.bridge.xyz/v0
  description: The base path for all resources
security:
- ApiKey: []
tags:
- name: Rewards
paths:
  /rewards/{currency}:
    get:
      summary: Get a summary of all rewards for a given stablecoin
      description: Get a summary of all rewards for a given stablecoin
      tags:
      - Rewards
      parameters:
      - $ref: '#/components/parameters/RewardCurrencyParameter'
      responses:
        '200':
          description: The summary of all rewards for a given stablecoin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperRewardSummary'
              examples:
                RewardSummary:
                  $ref: '#/components/examples/DeveloperRewardSummary'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /rewards/{currency}/history:
    get:
      summary: Get daily reward history for a stablecoin
      description: Returns paginated daily reward records with per-provider breakdowns, AUM, fees, and distribution status. Data is calculated with a t-2 business day lag; the most recent available record corresponds to two business days prior to the current date.
      tags:
      - Rewards
      parameters:
      - $ref: '#/components/parameters/RewardCurrencyParameter'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 90
          default: 30
        description: Number of days to return per page
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor from a previous response
      responses:
        '200':
          description: Daily reward history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperRewardHistory'
              examples:
                DeveloperRewardHistory:
                  $ref: '#/components/examples/DeveloperRewardHistory'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /rewards/{currency}/customer/{customerID}:
    get:
      summary: Get a summary of a customer's rewards
      description: Get a summary of a customer's rewards
      tags:
      - Rewards
      parameters:
      - $ref: '#/components/parameters/RewardCurrencyParameter'
      - $ref: '#/components/parameters/CustomerIDParameter'
      responses:
        '200':
          description: The summary of a customer's rewards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerRewardSummary'
              examples:
                CustomerRewardSummary:
                  $ref: '#/components/examples/CustomerRewardSummary'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /rewards/{currency}/customer/{customerID}/history:
    get:
      summary: Get a history of a customer's rewards
      description: Get a history of a customer's rewards. Data is calculated with a t-2 business day lag; the most recent available record corresponds to two business days prior to the current date.
      tags:
      - Rewards
      parameters:
      - $ref: '#/components/parameters/RewardCurrencyParameter'
      - $ref: '#/components/parameters/CustomerIDParameter'
      responses:
        '200':
          description: The history of a customer's rewards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerRewardHistory'
              examples:
                CustomerRewardHistory:
                  $ref: '#/components/examples/CustomerRewardHistory'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
components:
  responses:
    AuthenticationError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            MissingTokenError:
              summary: No Api-Key header
              description: The header may be missing or misspelled.
              value:
                code: required
                location: header
                name: Api-Key
                message: Missing Api-Key header
            InvalidTokenError:
              summary: Invalid key in Api-Key header
              value:
                code: invalid
                location: header
                name: Api-Key
                message: Invalid Api-Key header
    BadRequestError:
      description: Request containing missing or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BadCustomerRequestErrorExample:
              summary: Bad customer request
              value:
                code: bad_customer_request
                message: fields missing from customer body.
                name: first_name,ssn
    UnexpectedError:
      description: Unexpected error. User may try and send the request again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UnexpectedError:
              summary: An unexpected error
              value:
                errors:
                - code: unexpected
                  message: An expected error occurred, you may try again later
  schemas:
    Error:
      required:
      - code
      - message
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 256
        message:
          type: string
          minLength: 1
          maxLength: 512
        source:
          title: ErrorSource
          required:
          - location
          - key
          properties:
            location:
              type: string
              enum:
              - path
              - query
              - body
              - header
            key:
              type: string
              description: Comma separated names of the properties or parameters causing the error
    Id:
      description: A UUID that uniquely identifies a resource
      type: string
      pattern: '[a-z0-9]*'
      minLength: 1
      maxLength: 42
    DeveloperRewardHistory:
      title: Developer Daily Reward History
      type: object
      properties:
        currency:
          type: string
          description: The stablecoin symbol
        developer_id:
          type: string
          description: The developer ID
        reserves_currency:
          type: string
          description: The denomination currency for all monetary amounts
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                description: The reward calculation date (YYYY-MM-DD)
              distributed:
                type: boolean
                description: Whether rewards for this date have been distributed
              total:
                type: object
                properties:
                  aum:
                    type: string
                    description: Developer AUM across all providers
                  developer_rewards:
                    type: string
                    description: Gross rewards (net of premint yield)
                  net_rewards:
                    type: string
                    description: Net rewards after fees
                  bridge_fee_bps:
                    type: string
                    description: Effective fee rate for that day
                  bridge_fee:
                    type: string
                    description: Fee amount for that day
                  annualized_yield_bps:
                    type: string
                    description: Blended annualized yield across providers
              providers:
                type: array
                items:
                  type: object
                  properties:
                    provider:
                      type: string
                      description: Provider identifier
                    aum:
                      type: string
                      description: Developer AUM held at this provider
                    developer_rewards:
                      type: string
                      description: Gross rewards from this provider
                    annualized_yield_bps:
                      type: string
                      description: Annualized yield rate for this provider
        pagination:
          type: object
          properties:
            has_more:
              type: boolean
              description: Whether more pages are available
            next_cursor:
              type: string
              nullable: true
              description: Cursor for the next page
    DeveloperRewardSummary:
      title: Reward Summary for a given stablecoin
      type: object
      properties:
        developer_id:
          type: string
          description: The developer ID of the developer
        currency:
          type: string
          description: The stablecoin symbol for the reward summary
        balance:
          type: string
          description: The balance of the developer in the given stablecoin
        rewards:
          type: string
          description: The rewards of the developer in the given stablecoin
        updated_at:
          type: string
          description: The timestamp of the last update to the reward summary, in ISO8601 format
    CustomerRewardHistory:
      title: Customer Reward History for a given stablecoin
      type: object
      properties:
        customer_id:
          type: string
          description: The customer ID of the customer
        rewards:
          type: array
          description: The rewards of the customer in the given stablecoin
          items:
            type: object
            properties:
              balance:
                type: string
                description: The balance of the customer in the given stablecoin
              amount:
                type: string
                description: The amount of the reward
              currency:
                type: string
                description: The stablecoin symbol for the reward summary
              date:
                type: string
                description: The date of the calculated reward
    CustomerRewardSummary:
      title: Customer Reward Summary for a given stablecoin
      type: object
      properties:
        developer_id:
          type: string
          description: The developer ID of the customer
        customer_id:
          type: string
          description: The customer ID of the customer
        currency:
          type: string
          description: The stablecoin symbol for the reward summary
        balance:
          type: string
          description: The balance of the customer in the given stablecoin
        rewards:
          type: string
          description: The rewards of the customer in the given stablecoin
        updated_at:
          type: string
          description: The timestamp of the last update to the reward summary, in ISO8601 format
  examples:
    CustomerRewardSummary:
      summary: A summary of a customer's rewards
      value:
        developer_id: 2d127766-02fa-44b0-9fc8-a67665dbf109
        customer_id: 02513e85-b0f9-4d79-8320-348ce9efaa11
        currency: xusd
        balance: '10000.00'
        rewards: '23.9725'
        updated_at: '2025-01-01T00:00:00.000Z'
    DeveloperRewardHistory:
      summary: Daily reward history for a stablecoin
      value:
        currency: usdb
        developer_id: 2d127766-02fa-44b0-9fc8-a67665dbf109
        reserves_currency: usd
        data:
        - date: '2026-04-20'
          distributed: false
          total:
            aum: '45000000.00'
            developer_rewards: '5390.41'
            net_rewards: '4851.37'
            bridge_fee_bps: '10.0000'
            bridge_fee: '539.04'
            annualized_yield_bps: '436.6667'
          providers:
          - provider: blackrock
            aum: '30000000.00'
            developer_rewards: '3561.64'
            annualized_yield_bps: '432.5000'
          - provider: superstate
            aum: '15000000.00'
            developer_rewards: '1828.77'
            annualized_yield_bps: '445.0000'
        pagination:
          has_more: true
          next_cursor: eyJkYXRlIjoiMjAyNi0wNC0yMCJ9
    CustomerRewardHistory:
      summary: A history of a customer's rewards
      value:
        customer_id: 02513e85-b0f9-4d79-8320-348ce9efaa11
        rewards:
        - balance: '10000.00'
          amount: '0.958904'
          currency: xusd
          date: '2025-01-02'
        - balance: '10100.00'
          amount: '0.968493'
          currency: xusd
          date: '2025-01-01'
    DeveloperRewardSummary:
      summary: A summary of all rewards for a given stablecoin
      value:
        developer_id: 2d127766-02fa-44b0-9fc8-a67665dbf109
        currency: xusd
        balance: '10000.00'
        rewards: '23.9725'
        updated_at: '2025-01-01T00:00:00.000Z'
  parameters:
    CustomerIDParameter:
      name: customerID
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    RewardCurrencyParameter:
      in: path
      name: currency
      required: true
      schema:
        type: string
      description: The stablecoin symbol
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Key
      in: header