Paxos Reward Addresses API

openapi: 3.2.0
info:
  title: Paxos Reward Addresses API
  version: '2.0'
  description: Welcome to Paxos APIs.
  x-logo:
    url: /docs/paxos.svg
    backgroundColor: '#FFFFFF'
    altText: Paxos logo
servers:
- url: https://api.paxos.com/v2
  description: Production
- url: https://api.sandbox.paxos.com/v2
  description: Sandbox
tags:
- name: Reward Addresses
  description: Reward addresses are blockchain addresses registered for reward attribution.
paths:
  /rewards/addresses:
    get:
      summary: List reward addresses
      description: Returns a paginated list of reward addresses
      operationId: ListAttributionAddresses
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAttributionAddressesResponse'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: customer_id
        description: Optional for public API - extracted from auth context if not provided.
        in: query
        required: false
        schema:
          type: string
      - name: ledger
        in: query
        required: false
        schema:
          type: string
          enum:
          - PAXOS
          - ETHEREUM
          - SOLANA
          - INK
          - XLAYER
          - ARBITRUM_ONE
          - ROBINHOOD
      - name: address
        in: query
        required: false
        schema:
          type: string
      - name: order
        description: Optional, sort order for results based on created_at. The default sort order is DESC.
        in: query
        required: false
        schema:
          type: string
          enum:
          - DESC
          - ASC
      - name: page_cursor
        description: Optional, cursor token for fetching the next page.
        in: query
        required: false
        schema:
          type: string
      - name: id
        description: Optional, address id.
        in: query
        required: false
        schema:
          type: string
      - name: payout_group_id
        description: Optional, filter by payout group. Pass the zero UUID (00000000-0000-0000-0000-000000000000) to return only addresses with no payout group assigned.
        in: query
        required: false
        schema:
          type: string
      - name: include_balance
        description: When true, fetch and include balance for each address
        in: query
        required: false
        schema:
          type: boolean
      - name: balance_timestamp
        description: Point-in-time for balance query (optional, defaults to now)
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: asset_type
        description: When set, only addresses belonging to payout groups with this asset type are returned.
        in: query
        required: false
        schema:
          type: string
      - name: onchain_statuses
        description: Optional, filter by one or more onchain registration statuses.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - ONCHAIN_STATUS_TYPE_UNSPECIFIED
            - UNREGISTERED
            - PENDING_REGISTRATION
            - NEEDS_REREGISTRATION
            - ACTIVE
            - FAILED_REGISTRATION
            - PENDING_DELETION
            - FAILED_DELETION
            - PENDING_MULTIPLIER_UPDATE
            - MULTIPLIER_UPDATE_FAILED
      tags:
      - Reward Addresses
      security:
      - OAuth2:
        - rewards:read_monitoring_address
    post:
      summary: Create a reward address
      description: Creates a new reward address for reward attribution
      operationId: CreateAttributionAddress
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAttributionAddressResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAttributionAddressRequest'
        required: true
      tags:
      - Reward Addresses
      security:
      - OAuth2:
        - rewards:write_monitoring_address
  /rewards/addresses/batch:
    post:
      summary: Batch create reward addresses
      description: Creates multiple reward addresses in a single request
      operationId: BatchCreateAttributionAddresses
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateAttributionAddressesResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateAttributionAddressesRequest'
        required: true
      tags:
      - Reward Addresses
      security:
      - OAuth2:
        - rewards:write_monitoring_address
  /rewards/addresses/{id}:
    delete:
      summary: Delete a reward address
      description: Deletes a reward address. A 200 response indicates the request was accepted; however, if the address is registered on a blockchain, it may continue to appear for up to a few minutes while the on-chain removal is confirmed. Once confirmed, the address will no longer appear.
      operationId: DeleteAttributionAddress
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAttributionAddressResponse'
      parameters:
      - name: id
        description: 'Two deletion modes are supported:

          1. ID-based (REST API): Provide ''id'', customer_id is extracted from auth context.

          2. Legacy (internal gRPC): Provide ''customer_id'', ''ledger'', and ''address''.


          Address ID for deletion (preferred for REST API).'
        in: path
        required: true
        schema:
          type: string
      - name: customer_id
        description: Partner ID (used for legacy deletion or when auth context unavailable).
        in: query
        required: false
        schema:
          type: string
      - name: ledger
        description: Ledger type (required for legacy deletion).
        in: query
        required: false
        schema:
          type: string
          enum:
          - PAXOS
          - ETHEREUM
          - SOLANA
          - INK
          - XLAYER
          - ARBITRUM_ONE
          - ROBINHOOD
      - name: address
        description: Wallet address (required for legacy deletion).
        in: query
        required: false
        schema:
          type: string
      tags:
      - Reward Addresses
      security:
      - OAuth2:
        - rewards:write_monitoring_address
    put:
      summary: Update a reward address
      description: Updates an existing reward address
      operationId: UpdateAttributionAddress
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAttributionAddressResponse'
      parameters:
      - name: id
        description: 'id is the address ID used as the URL path parameter.

          Must match address.id when both are provided.'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributionAddress'
        required: true
      tags:
      - Reward Addresses
      security:
      - OAuth2:
        - rewards:write_monitoring_address
components:
  schemas:
    AttributionLedgerType:
      type: string
      enum:
      - PAXOS
      - ETHEREUM
      - SOLANA
      - INK
      - XLAYER
      - ARBITRUM_ONE
      - ROBINHOOD
      description: 'An AttributionLedgerType is a data source which produces events which cause monitored

        to occur. Examples include blockchains and the Paxos platform. Each event includes

        a source and/or destination address which will be compared against the addresses

        configured relative to the same ledger type.'
    DeleteAttributionAddressResponse:
      type: object
    CreateAttributionAddressResponse:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AttributionAddress'
    BatchCreateAttributionAddressesRequest:
      type: object
      properties:
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/AttributionAddress'
    CreateAttributionAddressRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AttributionAddress'
    BatchCreateAttributionAddressesResponse:
      type: object
      properties:
        successful_addresses:
          type: array
          items:
            $ref: '#/components/schemas/AttributionAddress'
        failed_addresses:
          type: array
          items:
            $ref: '#/components/schemas/AttributionAddressError'
    AttributionAddress:
      type: object
      properties:
        customer_id:
          type: string
          title: 'ie: partner_id'
        ledger:
          $ref: '#/components/schemas/AttributionLedgerType'
        address:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        effective_at:
          type: string
          format: date-time
        id:
          type: string
          title: 'ie: address ID'
        payout_group_id:
          type: string
          title: UUID of the payout group this address belongs to
        balance:
          type: string
          title: Total custody at address (only populated when include_balance=true in request)
        status:
          type: string
          description: Output only. Registration status (UNREGISTERED, PENDING, ACTIVE, FAILED). Server-managed; ignored on create/update.
          readOnly: true
        asset_type:
          type: string
          description: Asset this address is scoped to (e.g. "PYUSD", "USDG"). Null/empty means all assets.
        verification_proof_id:
          type: string
          description: Output only. ID of the latest address-ownership proof. Absent when no proof exists.
          readOnly: true
        verification_status:
          type: string
          description: Output only. Status of the latest proof (PENDING, APPROVED, EXPIRED). Absent when no proof exists.
          readOnly: true
        verification_method:
          type: string
          description: Output only. Method of the latest proof (SIGNATURE, SMALL_DEPOSIT, MANUAL). Absent when no proof exists.
          readOnly: true
        verification_expires_at:
          type: string
          format: date-time
          description: Output only. Expiry of the latest proof. Absent when no proof exists.
          readOnly: true
      title: All data associated with an attribution address
    ListAttributionAddressesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AttributionAddress'
          description: Monitored addresses in this page of results.
        next_page_cursor:
          type: string
          description: Token for the next page of results; empty if no more results.
    AttributionAddressError:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AttributionAddress'
        error:
          type: string
          title: Error message
      title: Failed address with error details
    UpdateAttributionAddressResponse:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AttributionAddress'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'Paxos APIs use [OAuth 2](https://tools.ietf.org/html/rfc6749) with the [client credentials](https://tools.ietf.org/html/rfc6749#section-4.4) grant flow.


        **Token URLs:**

        - Production: https://oauth.paxos.com/oauth2/token

        - Sandbox: https://oauth.sandbox.paxos.com/oauth2/token


        Learn more in the [API credentials guide →](https://docs.paxos.com/developer/credentials)

        '
      flows:
        clientCredentials:
          tokenUrl: https://oauth.paxos.com/oauth2/token
          scopes:
            conversion:read_conversion_stablecoin: Retrieve stablecoin conversion details
            conversion:write_conversion_stablecoin: Create or cancel a stablecoin conversion
            exchange:historical_prices: Retrieve marketnaverage prices at a certain time increment
            exchange:read_order: Retrieve order or order execution details
            exchange:read_quote: Retrieve quote details for buying or selling an asset
            exchange:read_quote_execution: Retrieve quote execution details
            exchange:write_quote_execution: Create a quote execution for buying or selling an asset
            exchange:write_order: Create or cancel an order for buying or selling an asset
            fee:write_crypto_withdrawal_fee: Create a guaranteed fee for crypto withdrawal
            funding:read_bank_balance: Retrieve Paxos dedicated bank account balance
            funding:read_profile: Retrieve Profile details and deposit funds in Sandbox
            funding:write_profile: Create a Profile
            identity:read_account: Retrieve Account details
            identity:read_identity: Retrieve Identity details or documents
            identity:write_account: Create or update Account and Account Members
            identity:write_identity: Create or update Identity details and set Sandbox Identify Status
            settlement:read_transaction: Retrieve settlement transaction details
            settlement:write_transaction: Create, affirm or cancel a settlement transaction
            tax:read_tax_form: Retrieve tax details
            tax:read_tax_lot: Retrieve tax lot details
            tax:write_tax_lot: Update the given tax-lot ID
            transfer:read_deposit_address: Retrieve deposit address details
            transfer:read_fiat_account: Retrieve Fiat Account details
            transfer:read_fiat_deposit_instructions: Retrieve fiat deposit instruction details
            transfer:read_transfer: Retrieve transfer details
            transfer:read_transfer_limit: Retrieve limits for the given transaction type
            transfer:reject_crypto_deposit: Reject a crypto deposit (travel rule)
            transfer:update_crypto_deposit: Provide required travel-rule details
            transfer:write_crypto_withdrawal: Withdraw asset to a specified destination address
            transfer:write_deposit_address: Create an deposit address on a blockchain network
            transfer:write_fiat_account: Create, update or delete a Fiat Account
            transfer:write_fiat_deposit_instructions: Create, update or delete fiat deposit instructions
            transfer:write_internal_transfer: Transfer assets between two Profiles
            transfer:write_sandbox_fiat_deposit: Initiate a test fiat deposit in the Sandbox environment
            transfer:write_fiat_withdrawal: Withdraw fiat to the given destination
            events:read_event: Retrieve events
x-tagGroups:
- name: Deposits and Withdrawals
  tags:
  - Transfers
  - Fiat Transfers
  - Deposit Addresses
  - Crypto Deposits
  - Crypto Withdrawals
  - Fees
  - Internal Transfers
  - Paxos Transfers
  - Limits
- name: Identity
  tags:
  - Identity
  - Institution Members
  - Accounts
  - Account Members
  - Identity Documents
- name: API Credentials
  tags:
  - API Credentials
- name: Profiles
  tags:
  - Profiles
- name: Sandbox
  tags:
  - Sandbox Deposits
  - Sandbox Identity
  - Sandbox Fiat Transfers
- name: Settlements
  tags:
  - Settlement
- name: Stablecoin Conversion
  tags:
  - Stablecoin Conversion
- name: Taxes
  tags:
  - Tax Forms
- name: Trading
  tags:
  - Market Data
  - Orders
  - Quotes
  - Quote Executions
  - Pricing
  - Issuer Quotes
- name: Rewards
  tags:
  - Monitoring Addresses
  - Statements
  - Payments
- name: Rewards (Alpha)
  tags:
  - Reward Addresses
  - Claims
  - Payout Groups
  - Rewards
- name: Events
  tags:
  - Events
  - Event Types
  - Event Objects