Paxos Statements API

openapi: 3.0.0
info:
  title: Paxos Account Members Statements API
  version: '2.0'
  description: '<p>Welcome to Paxos APIs. At Paxos, our mission is to enable the movement of any asset, any time, in a trustworthy way. These APIs serve that mission by making it easier than ever for you to directly integrate our product capabilities into your application, leveraging the speed, stability, and security of the Paxos platform.</p> <p>The documentation that follows gives you access to our Crypto Brokerage, Trading, and Exchange products. It includes APIs for market data, orders, and the held rate quote flow.</p> <p>To test in our sandbox environment, <a href="https://account.sandbox.paxos.com" target="_blank">sign up</a> for an account. For more information about Paxos and our APIs, visit <a href="https://www.paxos.com/" target="_blank">Paxos.com</a>.</p>

    '
  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: Statements
  description: 'A Statement summarizes all eligible stablecoin rewards for a given organization over a fixed time period. It aggregates earned reward types (e.g., custody, mint, acceptance) and records whether the statement was paid.


    Statements are generated monthly and are immutable. Revised statements will be issued as a new statement with a unique ID. Statements can be used to reconcile balances or for accounting and accounts receivable purposes.


    *These endpoints are only relevant for Global Dollar Network (GDN) partners.*

    '
paths:
  /statements:
    get:
      summary: List Statements
      description: List statements based on the provided filters
      operationId: ListStatements
      responses:
        '200':
          description: Successfully retrieve statements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListStatementsResponse'
              examples:
                Retrieve statements:
                  value:
                    statements:
                    - id: 704b4e48-bbb1-4086-b6e4-6e9b2e3e5d7a
                      ref_id: USDG_REWARDS-cdcbff8e-cf51-4536-ba6f-92ef6846e48a-2025-02
                      customer_id: cdcbff8e-cf51-4536-ba6f-92ef6846e48a
                      type: STATEMENT_TYPE_USDG_REWARD
                      product: USDG_REWARDS
                      status: STATEMENT_STATUS_PAID
                      metadata:
                        total_amount: '100.5'
                      statement_balances:
                      - asset: USDG
                        amount_paid: '100.5'
                        total_amount_owed: '100.5'
                      period_start: '2025-02-01T00:00:00Z'
                      period_end: '2025-02-28T23:59:59.999999Z'
                      generated_at: '2025-03-18T23:11:47.840321Z'
                      paid_at: '2025-03-19T19:21:57.172302Z'
                      created_at: '2025-03-18T23:11:47.627302Z'
                    - id: 30ed2047-6155-4b75-b235-6600aa7f65dd
                      ref_id: USDG_REWARDS-cdcbff8e-cf51-4536-ba6f-92ef6846e48a-2025-03
                      customer_id: cdcbff8e-cf51-4536-ba6f-92ef6846e48a
                      type: STATEMENT_TYPE_USDG_REWARD
                      product: USDG_REWARDS
                      status: STATEMENT_STATUS_PAID
                      metadata:
                        total_amount: '100.5'
                      statement_balances:
                      - asset: USDG
                        amount_paid: '100.5'
                        total_amount_owed: '100.5'
                      period_start: '2025-02-18T00:00:00Z'
                      period_end: '2025-03-18T00:00:00Z'
                      generated_at: '2025-03-18T19:11:54.606991Z'
                      paid_at: '2025-03-20T14:26:06.649645Z'
                      created_at: '2025-03-18T19:11:54.372336Z'
      parameters:
      - name: customer_id
        description: customer_id is a required field.
        in: query
        required: false
        schema:
          type: string
      - name: ref_ids
        description: Optionally filter by the ref_ids of the statements.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: statement_ids
        description: Optionally filter by the ids of the statements.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: statuses
        description: Optionally filter by the statuses of the statements to be returned. Defaults to all statuses.
        in: query
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - STATEMENT_STATUS_UNSPECIFIED
            - STATEMENT_STATUS_INITIATED
            - STATEMENT_STATUS_GENERATED
            - STATEMENT_STATUS_PAID
      - name: limit
        description: Number of results to return. Defaults to 100.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: order
        description: Sort order for the results by period start, defaults to DESC if not provided.
        in: query
        required: false
        schema:
          type: string
          enum:
          - DESC
          - ASC
      - name: page_cursor
        description: Cursor for getting the next page of results.
        in: query
        required: false
        schema:
          type: string
      tags:
      - Statements
      deprecated: true
      security:
      - OAuth2:
        - statements:read_statement
components:
  schemas:
    StatementBalance:
      type: object
      properties:
        asset:
          type: string
        amount_paid:
          type: string
          format: decimal
        total_amount_owed:
          type: string
          format: decimal
        next_payment_ref_id:
          type: string
          description: 'next_payment_ref_id should be used by clients as the ref_id when processing payments for statements.

            This is unique to for each payment that should be submitted. If the amount_paid == total_amount_owed, then this field will be empty.'
    StatementStatus:
      type: string
      enum:
      - STATEMENT_STATUS_UNSPECIFIED
      - STATEMENT_STATUS_INITIATED
      - STATEMENT_STATUS_GENERATED
      - STATEMENT_STATUS_PAID
    Product:
      type: string
      enum:
      - USDG_REWARDS
    StatementFile:
      type: object
      properties:
        format:
          type: string
          title: The format type (e.g., "PDF" or "CSV")
        url:
          type: string
          title: The S3 presigned URL for the file
        expires_at:
          type: string
          format: date-time
          title: When the S3 presigned URL expires
        generated_at:
          type: string
          format: date-time
          title: Timestamp when this specific file was generated
      description: Represents a generated file for a specific statement version.
    bufAny:
      type: object
      properties:
        '@type':
          type: string
          description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
      additionalProperties: {}
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n    // or ...\n    if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n      foo = any.unpack(Foo.getDefaultInstance());\n    }\n\n Example 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\n Example 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    ListStatementsResponse:
      type: object
      properties:
        statements:
          type: array
          items:
            $ref: '#/components/schemas/Statement'
        next_page_cursor:
          type: string
    StatementType:
      type: string
      enum:
      - STATEMENT_TYPE_UNSPECIFIED
      - STATEMENT_TYPE_USDG_REWARD
    Statement:
      type: object
      properties:
        id:
          type: string
          description: Unique statement ID.
        ref_id:
          type: string
          description: Must be unique per customer.
        customer_id:
          type: string
          description: UUID of the associated customer.
        type:
          $ref: '#/components/schemas/StatementType'
        product:
          $ref: '#/components/schemas/Product'
        status:
          $ref: '#/components/schemas/StatementStatus'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom fields (e.g., `total_amount`).
        statement_balances:
          type: array
          items:
            $ref: '#/components/schemas/StatementBalance'
          description: Breakdown of owed vs. paid balances.
        period_start:
          type: string
          format: date-time
          description: The time range this statement covers.
        period_end:
          type: string
          format: date-time
          description: The time range this statement covers.
        generated_at:
          type: string
          format: date-time
          description: Lifecycle tracking fields.
        paid_at:
          type: string
          format: date-time
          description: Lifecycle tracking fields.
        created_at:
          type: string
          format: date-time
          description: Lifecycle tracking fields.
        statement_group_id:
          type: string
          description: statement_group_id is used to group multiple statements together. Multiple versions of a statement may belong to a single statement group.
        version:
          type: integer
          format: int64
          description: Version number of the statement.
        files:
          type: array
          items:
            $ref: '#/components/schemas/StatementFile'
          title: Generated files for the statement
        data:
          $ref: '#/components/schemas/bufAny'
  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