Paxos Deposit Addresses API

openapi: 3.2.0
info:
  title: Paxos Deposit 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: Deposit Addresses
paths:
  /transfer/deposit-addresses:
    get:
      summary: List Deposit Addresses
      description: List all deposit addresses, optionally filtering and paging the results.
      operationId: ListDepositAddresses
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDepositAddressesResponse'
      parameters:
      - name: profile_ids
        description: Optionally filter by the profile IDs associated with the deposit addresses. Limit 100.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: identity_ids
        description: Optionally filter by the Identities associated with the deposit addresses. Limit 100.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: ids
        description: Optionally filter by the UUIDs of the deposit addresses. Limit 100.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: ref_ids
        description: The client-specified IDs provided during transfer creation. Limit 100.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: created_at.lt
        description: Include timestamps strictly less than lt. RFC3339 format, like `2006-01-02T15:04:05Z`.
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at.lte
        description: Include timestamps less than or equal to lte. RFC3339 format, like `2006-01-02T15:04:05Z`.
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at.eq
        description: Include timestamps exactly equal to eq. RFC3339 format, like `2006-01-02T15:04:05Z`.
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at.gte
        description: Include timestamps greater than or equal to gte. RFC3339 format, like `2006-01-02T15:04:05Z`.
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at.gt
        description: Include timestamps strictly greater than gt. RFC3339 format, like `2006-01-02T15:04:05Z`.
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        description: Number of results to return. Defaults to 100 if no limit is provided. Maximum 1000.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: order
        description: Return items in ascending (ASC) or descending (DESC) order. Defaults to DESC.
        in: query
        required: false
        schema:
          type: string
          enum:
          - DESC
          - ASC
      - name: order_by
        description: The specific method by which the returned results will be ordered.
        in: query
        required: false
        schema:
          type: string
          enum:
          - CREATED_AT
      - name: page_cursor
        description: 'Optional: Cursor for getting the next page of results.'
        in: query
        required: false
        schema:
          type: string
      - name: account_ids
        description: Optionally filter by the Accounts associated with the deposit address. Limit 100.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: networks
        description: Optionally filter by the networks of the deposit addresses. Limit 100.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - BITCOIN
            - ETHEREUM
            - BITCOIN_CASH
            - LITECOIN
            - SOLANA
            - POLYGON_POS
            - BASE
            - ARBITRUM_ONE
            - STELLAR
            - INK
            - XLAYER
            - AVALANCHE
            - DOGECOIN
            - SUI
            - ROBINHOOD
            - BNB
      tags:
      - Deposit Addresses
      security:
      - OAuth2:
        - transfer:read_deposit_address
    post:
      summary: Create Deposit Address
      description: 'Create a deposit address on a blockchain network for depositing to a profile.


        **Important for Stellar Network (PYUSD):**


        When creating a deposit address for PYUSD on the Stellar network:


        - Paxos automatically handles all necessary setup including trustline establishment

        - The deposit address is immediately ready to receive PYUSD tokens

        - No additional configuration is required by the user

        - The PYUSD issuer address on Stellar mainnet is: `GDQE7IXJ4HUHV6RQHIUPRJSEZE4DRS5WY577O2FY6YQ5LVWZ7JZTU2V5`

        - The PYUSD asset code is: `PYUSD`'
      operationId: CreateDepositAddress
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositAddress'
              example:
                id: 34bd61ed-cf0a-4012-8be4-d347667b6154
                profile_id: b7b77d82-e6a7-4ae9-9904-36231aedf985
                customer_id: 9b8c9cba-801e-4418-adc0-ede709df6339
                identity_id: 54385e67-d7ef-40d1-b488-ceda6dd9b264
                ref_id: deposit_address_0
                crypto_network: ETHEREUM
                address: '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7'
                conversion_target_asset: USD
                compatible_crypto_networks:
                - ETHEREUM
                - POLYGON_POS
                - BASE
                - ARBITRUM_ONE
                - INK
                - XLAYER
                metadata:
                  my_id: 4024ee50-eefb-4f2e-85c7-e7899c0b7da5
                created_at: '2020-01-17T18:36:08.737Z'
        '409':
          description: Deposit address already exists
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Already Exists:
                  $ref: '#/components/examples/Problem_already_exists_deposit_address'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDepositAddressRequest'
        required: true
      tags:
      - Deposit Addresses
      security:
      - OAuth2:
        - transfer:write_deposit_address
components:
  examples:
    Problem_already_exists_deposit_address:
      value:
        type: https://developer.paxos.com/docs/v2/problems/already-exists
        title: Already Exists
        status: 409
        detail: deposit address already exists with ref_id 'already_used_ref_id'
        meta:
          existing:
            id: 34bd61ed-cf0a-4012-8be4-d347667b6154
            profile_id: b7b77d82-e6a7-4ae9-9904-36231aedf985
            customer_id: 9b8c9cba-801e-4418-adc0-ede709df6339
            crypto_network: ETHEREUM
            identity_id: 54385e67-d7ef-40d1-b488-ceda6dd9b264
            ref_id: already_used_ref_id
            metadata:
              my_id: 4024ee50-eefb-4f2e-85c7-e7899c0b7da5
            address: '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7'
  schemas:
    CryptoNetwork:
      type: string
      enum:
      - BITCOIN
      - ETHEREUM
      - BITCOIN_CASH
      - LITECOIN
      - SOLANA
      - POLYGON_POS
      - BASE
      - ARBITRUM_ONE
      - STELLAR
      - INK
      - XLAYER
      - AVALANCHE
      - DOGECOIN
      - SUI
      - ROBINHOOD
      - BNB
      description: A CryptoNetwork is a blockchain transmitting cryptocurrencies.
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type.  When dereferenced,

            it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
          example: https://api.paxos.com/v2/problems/insufficient_funds
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable

            '
          example: Insufficient Funds
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          example: 403
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Not enough funds in account.
        meta:
          type: object
          description: 'Additional structured metadata about the error.

            '
    DepositAddressConversionTargetAsset:
      type: string
      enum:
      - NO_CONVERSION
      - USD
      description: Asset to credit for deposits of Paxos-minted USD stablecoin.
    DepositAddress:
      type: object
      example:
        id: 34bd61ed-cf0a-4012-8be4-d347667b6154
        profile_id: b7b77d82-e6a7-4ae9-9904-36231aedf985
        customer_id: 9b8c9cba-801e-4418-adc0-ede709df6339
        identity_id: 54385e67-d7ef-40d1-b488-ceda6dd9b264
        ref_id: deposit_address_0
        crypto_network: ETHEREUM
        address: '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7'
        conversion_target_asset: USD
        compatible_crypto_networks:
        - ETHEREUM
        metadata:
          my_id: 4024ee50-eefb-4f2e-85c7-e7899c0b7da5
        created_at: '2020-01-17T18:36:08.737Z'
      properties:
        id:
          type: string
          description: The UUID of the deposit address.
        profile_id:
          type: string
          description: The ID of the profile that will be credited when a deposit arrives with this address.
        customer_id:
          type: string
          description: The Paxos Customer to which the profile belongs.
        crypto_network:
          $ref: '#/components/schemas/CryptoNetwork'
        identity_id:
          type: string
          description: The Identity of the end user who will make deposits to this address.
        ref_id:
          type: string
          description: Client-specified ID for replay protection and lookup.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: 'Optional client-specified metadata, which is set on deposit address creation.

            Up to 6 key/value pairs may be returned.

            Each key and value must be less than or equal to 100 characters.'
        address:
          type: string
          description: The crypto address to send to for deposits.
        account_id:
          type: string
          description: The Account associated to the identity of the user that will be linked to the created address.
        conversion_target_asset:
          $ref: '#/components/schemas/DepositAddressConversionTargetAsset'
        compatible_crypto_networks:
          type: array
          items:
            $ref: '#/components/schemas/CryptoNetwork'
          description: List of networks compatible with the created address. Any of these networks can be used to deposit to the address.
        created_at:
          type: string
          format: date-time
          description: The time at which this address was created.
      required:
      - id
      - profile_id
      - customer_id
      - crypto_network
      - address
      - conversion_target_asset
      - created_at
    ListDepositAddressesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DepositAddress'
        next_page_cursor:
          type: string
    CreateDepositAddressRequest:
      type: object
      example:
        profile_id: b7b77d82-e6a7-4ae9-9904-36231aedf985
        crypto_network: ETHEREUM
        identity_id: 54385e67-d7ef-40d1-b488-ceda6dd9b264
        ref_id: deposit_address_0
        metadata:
          my_id: 4024ee50-eefb-4f2e-85c7-e7899c0b7da5
      properties:
        profile_id:
          type: string
          description: The target profile for deposit crediting.
        crypto_network:
          $ref: '#/components/schemas/CryptoNetwork'
        identity_id:
          type: string
          description: The Paxos Identity associated with this deposit address.
        ref_id:
          type: string
          description: Client-specified ID for replay protection and lookup.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: 'Optional client-specified metadata, which will be added to both the deposit address itself and transfers to the created address.

            Up to 6 key/value pairs may be provided.

            Each key and value must be less than or equal to 100 characters.'
        account_id:
          type: string
          description: The Paxos Account associated with this deposit address.
        conversion_target_asset:
          $ref: '#/components/schemas/DepositAddressConversionTargetAsset'
      required:
      - profile_id
      - crypto_network
  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