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

# Get a customer's PIX destinations.



## OpenAPI

````yaml /spec.yaml get /addresses/pix/{customer_id}
openapi: 3.1.0
info:
  description: The Stablecoin Payment Network
  title: Iron API - Sandbox
  version: 1.0-17138
servers:
  - url: https://api.sandbox.iron.xyz/api
security: []
tags:
  - description: >-
      Wallet and bank account registration


      Every wallet address that interacts with Iron must be registered (linked)
      to a customer **before** it can be used in any flow — onramp, offramp, or
      swap. This is a regulatory requirement under the **Travel Rule**, which
      obliges Virtual Asset Service Providers to exchange originator and
      beneficiary information for crypto transfers.


      Iron supports two wallet types:


      - **Self-hosted wallets** — the customer controls the private key.
      Registration requires a signed proof-of-ownership message.

      - **Hosted wallets** — the wallet is custodied by another VASP (e.g.
      Coinbase, Kraken). Registration requires the VASP's DID so Iron can
      exchange travel-rule data with the custodian.


      Similarly, fiat bank accounts must be registered before they can receive
      offramp payouts.
    name: Addresses
  - description: Operations on Autoramp
    name: Autoramp
  - description: Operations on Chronicle collateral
    name: ChronicleCollateral
  - description: Operations on Currencies
    name: Currencies
  - description: Operations on Customers
    name: Customer
  - description: Operations on Exchange Rate
    name: ExchangeRate
  - description: Operations on Fee Profiles
    name: FeeProfiles
  - description: Operations for Sandbox Testing
    name: Sandbox
  - description: Operations on SSE
    name: Sse
  - description: Operations on Terms and Conditions
    name: TermsAndConditions
  - description: Operations on Webhooks
    name: Webhooks
paths:
  /addresses/pix/{customer_id}:
    get:
      tags:
        - Addresses
      summary: Get a customer's PIX destinations.
      operationId: getPixAddresses
      parameters:
        - deprecated: false
          description: the ID of the customer
          explode: true
          in: path
          name: customer_id
          required: true
          schema:
            format: uuid
            type: string
        - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/PagedList_PixAddress'
          description: GET Addresses Succeeded
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: GET Addresses Failed (Bad Request)
        '401':
          description: GET Addresses Failed (Unauthorized)
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: GET Addresses Failed (Internal Error)
      security:
        - ApiKeyAuth: []
components:
  parameters:
    XApiVersion:
      description: >-
        Selects the API version for this request, as an ISO date (`YYYY-MM-DD`).
        Omit to use the default version (`2025-03-13`). Supported versions:
        2025-03-13, 2026-07-01.
      in: header
      name: X-API-Version
      required: false
      schema:
        type: string
  schemas:
    PagedList_PixAddress:
      description: |
        PagedList

        A list of items with cursors used to fetch the next or previous page
      properties:
        cursor:
          description: The cursor used to fetch the next page
          format: uuid
          type: string
        items:
          description: The list of items
          items:
            $ref: '#/components/schemas/PixAddress'
          type: array
        prev_cursor:
          default: null
          description: The cursor used to fetch the previous page
          format: uuid
          type: string
      required:
        - items
      title: PagedList_PixAddress
      type: object
    ApiError:
      description: |-
        Standard error response returned to API clients for server errors.
        Includes a trace_id that clients can reference when reporting issues.
      properties:
        message:
          description: Human-readable error message
          type: string
        trace_id:
          description: Trace ID that can be used to look up request details in logs
          type: string
      required:
        - message
        - trace_id
      title: ApiError
      type: object
    PixAddress:
      description: |-
        PIX Address

        Response containing PIX destination details.
      example:
        created_at: '2024-01-15T10:30:00.000Z'
        customer_id: 123e4567-e89b-12d3-a456-426614174000
        id: 550e8400-e29b-41d4-a716-446655440000
        label: Primary PIX
        recipient:
          account:
            key: '+5511987654321'
            type: PHONE
          recipient:
            family_name: Turing
            given_name: Alan
            type: Individual
          tax_id: '12345678909'
        status: Registered
        updated_at: '1970-01-01T00:00:00.000Z'
      properties:
        created_at:
          description: When the address was created
          format: date-time
          type: string
        customer_id:
          description: The customer ID
          format: uuid
          type: string
        id:
          description: The ID of the address
          format: uuid
          type: string
        label:
          description: Optional label for the address
          type: string
        recipient:
          $ref: '#/components/schemas/RecipientPix'
        status:
          $ref: '#/components/schemas/PixAddressStatus'
        updated_at:
          description: When the address was last updated
          format: date-time
          type: string
      required:
        - id
        - created_at
        - updated_at
        - customer_id
        - recipient
        - status
      title: PixAddress
      type: object
    RecipientPix:
      description: |-
        RecipientPix

        A PIX payout recipient.
      example:
        account:
          key: '+5511987654321'
          type: PHONE
        recipient:
          family_name: Turing
          given_name: Alan
          type: Individual
        tax_id: '12345678909'
      properties:
        account:
          $ref: '#/components/schemas/PixAccountIdentifier'
        recipient:
          $ref: '#/components/schemas/RecipientName'
        tax_id:
          description: |-
            The recipient's CPF (11 digits) or CNPJ (14 digits), with or without
            the usual `.`/`-`/`/` formatting. The payout is rejected if the
            destination account is not registered to this tax ID.
          pattern: >-
            ^([0-9]{11}|[0-9]{14}|[0-9]{3}\.[0-9]{3}\.[0-9]{3}-[0-9]{2}|[0-9]{2}\.[0-9]{3}\.[0-9]{3}/[0-9]{4}-[0-9]{2})$
          type: string
      required:
        - recipient
        - tax_id
        - account
      title: RecipientPix
      type: object
    PixAddressStatus:
      description: PIX Address Status
      enum:
        - RegistrationPending
        - Registered
        - RegistrationFailed
      type: string
    PixAccountIdentifier:
      anyOf:
        - $ref: '#/components/schemas/PixAccountIdentifier_PixCpfKey'
        - $ref: '#/components/schemas/PixAccountIdentifier_PixCnpjKey'
        - $ref: '#/components/schemas/PixAccountIdentifier_PixEmailKey'
        - $ref: '#/components/schemas/PixAccountIdentifier_PixPhoneKey'
        - $ref: '#/components/schemas/PixAccountIdentifier_PixEvpKey'
        - $ref: '#/components/schemas/PixAccountIdentifier_PixBankDetails'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
      discriminator:
        mapping:
          BANK_DETAILS:
            $ref: '#/components/schemas/PixAccountIdentifier_PixBankDetails'
          CNPJ:
            $ref: '#/components/schemas/PixAccountIdentifier_PixCnpjKey'
          CPF:
            $ref: '#/components/schemas/PixAccountIdentifier_PixCpfKey'
          EMAIL:
            $ref: '#/components/schemas/PixAccountIdentifier_PixEmailKey'
          EVP:
            $ref: '#/components/schemas/PixAccountIdentifier_PixEvpKey'
          PHONE:
            $ref: '#/components/schemas/PixAccountIdentifier_PixPhoneKey'
        propertyName: type
      type: object
    RecipientName:
      anyOf:
        - $ref: '#/components/schemas/RecipientName_IndividualName'
        - $ref: '#/components/schemas/RecipientName_BusinessName'
      discriminator:
        mapping:
          Business:
            $ref: '#/components/schemas/RecipientName_BusinessName'
          Individual:
            $ref: '#/components/schemas/RecipientName_IndividualName'
        propertyName: type
      type: object
    PixAccountIdentifier_PixCpfKey:
      allOf:
        - properties:
            type:
              enum:
                - CPF
              example: CPF
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/PixCpfKey'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
    PixAccountIdentifier_PixCnpjKey:
      allOf:
        - properties:
            type:
              enum:
                - CNPJ
              example: CNPJ
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/PixCnpjKey'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
    PixAccountIdentifier_PixEmailKey:
      allOf:
        - properties:
            type:
              enum:
                - EMAIL
              example: EMAIL
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/PixEmailKey'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
    PixAccountIdentifier_PixPhoneKey:
      allOf:
        - properties:
            type:
              enum:
                - PHONE
              example: PHONE
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/PixPhoneKey'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
    PixAccountIdentifier_PixEvpKey:
      allOf:
        - properties:
            type:
              enum:
                - EVP
              example: EVP
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/PixEvpKey'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
    PixAccountIdentifier_PixBankDetails:
      allOf:
        - properties:
            type:
              enum:
                - BANK_DETAILS
              example: BANK_DETAILS
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/PixBankDetails'
      description: |-
        PixAccountIdentifier

        How the recipient's PIX account is identified: a DICT key of one of the
        five key types, or full bank account details.
    RecipientName_IndividualName:
      allOf:
        - properties:
            type:
              enum:
                - Individual
              example: Individual
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/IndividualName'
    RecipientName_BusinessName:
      allOf:
        - properties:
            type:
              enum:
                - Business
              example: Business
              type: string
          required:
            - type
          type: object
        - $ref: '#/components/schemas/BusinessName'
    PixCpfKey:
      description: |-
        PixCpfKey

        A PIX DICT key that is the recipient's CPF.
      example:
        key: '12345678909'
      properties:
        key:
          description: 11-digit CPF, with or without the `XXX.XXX.XXX-XX` formatting
          pattern: ^([0-9]{11}|[0-9]{3}\.[0-9]{3}\.[0-9]{3}-[0-9]{2})$
          type: string
      required:
        - key
      title: PixCpfKey
      type: object
    PixCnpjKey:
      description: |-
        PixCnpjKey

        A PIX DICT key that is the recipient's CNPJ.
      example:
        key: '12345678000195'
      properties:
        key:
          description: 14-digit CNPJ, with or without the `XX.XXX.XXX/XXXX-XX` formatting
          pattern: ^([0-9]{14}|[0-9]{2}\.[0-9]{3}\.[0-9]{3}/[0-9]{4}-[0-9]{2})$
          type: string
      required:
        - key
      title: PixCnpjKey
      type: object
    PixEmailKey:
      description: |-
        PixEmailKey

        A PIX DICT key that is the recipient's email address.
      example:
        key: joao.silva@example.com
      properties:
        key:
          maxLength: 77
          pattern: ^[^@\s]+@[^@\s]+$
          type: string
      required:
        - key
      title: PixEmailKey
      type: object
    PixPhoneKey:
      description: |-
        PixPhoneKey

        A PIX DICT key that is the recipient's phone number.
      example:
        key: '+5511987654321'
      properties:
        key:
          description: International format with leading `+`, e.g. +5511987654321
          pattern: ^\+[1-9][0-9]{1,14}$
          type: string
      required:
        - key
      title: PixPhoneKey
      type: object
    PixEvpKey:
      description: |-
        PixEvpKey

        A random PIX DICT key (EVP) generated by the recipient's bank.
      example:
        key: 123e4567-e89b-12d3-a456-426614174000
      properties:
        key:
          description: A lowercase UUID, e.g. 123e4567-e89b-12d3-a456-426614174000
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          type: string
      required:
        - key
      title: PixEvpKey
      type: object
    PixBankDetails:
      description: |-
        PixBankDetails

        Full Brazilian bank account details identifying the recipient's account,
        for recipients without a registered PIX key.
      example:
        account_number: '5678901'
        account_type: CHECKING
        bank_code: '341'
        branch_code: '1234'
      properties:
        account_number:
          description: |-
            Account number including the verification (check) digit, with no
            separator, e.g. `7140025418`.
          maxLength: 20
          minLength: 1
          type: string
        account_type:
          $ref: '#/components/schemas/PixAccountType'
        bank_code:
          description: 3-digit COMPE bank code or 8-digit ISPB, distinguished by length
          pattern: ^([0-9]{3}|[0-9]{8})$
          type: string
        branch_code:
          description: Branch number without the verification digit
          pattern: ^[0-9]{1,4}$
          type: string
      required:
        - bank_code
        - branch_code
        - account_number
        - account_type
      title: PixBankDetails
      type: object
    IndividualName:
      example:
        family_name: Turing
        given_name: Alan
      properties:
        family_name:
          maxLength: 50
          minLength: 1
          type: string
        given_name:
          maxLength: 50
          minLength: 1
          type: string
      required:
        - given_name
        - family_name
      title: IndividualName
      type: object
    BusinessName:
      example:
        name: Aperture Science
      properties:
        name:
          maxLength: 50
          minLength: 1
          type: string
      required:
        - name
      title: BusinessName
      type: object
    PixAccountType:
      description: |-
        PixAccountType

        The type of a Brazilian bank account.
      enum:
        - CHECKING
        - SAVINGS
        - SALARY
        - TRANSACTION
      type: string
  securitySchemes:
    ApiKeyAuth:
      description: API Key
      in: header
      name: X-API-Key
      type: apiKey

````