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

# Get PAXG swap quote

> Returns swap calldata for buying or selling PAXG via DEX aggregators. Supports Ethereum mainnet (chainId 1). The response includes the target contract, encoded calldata, and expected output amount.



## OpenAPI

````yaml /v1.0.0/api-reference/openapi.yml get /v1/paxg/swapQuotes
openapi: 3.0.0
info:
  title: Paxos Labs API
  description: >
    Paxos Labs API V2.


    ---


    # API overview


    This document describes shared behavior and conventions for the Paxos Labs
    API (REST and GraphQL).


    <details>

    <summary><strong>Health check</strong></summary>


    A **health** endpoint is available for orchestrators (GitHub Actions, etc).


    | Item         |
    Details                                                                                
    |

    | ------------ |
    ---------------------------------------------------------------------------------------
    |

    | **Path**     | `GET /health` (no version prefix; no API key or rate limit
    applied).                    |

    | **Response** | `200` with Terminus-style JSON when healthy; `503` when
    unhealthy (e.g. database down). |


    **Docker / healthcheck:** If your healthcheck uses `curl` (e.g. `curl -f
    http://localhost:3000/health`), ensure your image has curl installed. Base
    images like `node:bullseye-slim` or `node:alpine` do not—install it (e.g.
    `RUN apk add --no-cache curl` for Alpine).


    </details>


    <details>

    <summary><strong>GraphQL endpoint</strong></summary>


    A **GraphQL** API is available in addition to REST. Use it to query address
    book and vault data with a single request and flexible field selection.


    | Item                         |
    Details                                                              |

    | ---------------------------- |
    -------------------------------------------------------------------- |

    | **Altair (interactive IDE)** |
    [https://api.paxoslabs.com/altair](https://api.paxoslabs.com/altair) |

    | **GraphQL endpoint**         | Same base URL with path `/graphql` for
    POST.                         |

    | **Authentication**           | Same as REST: send `x-api-key`
    header.                               |


    Open the Altair link in a browser to explore the schema and run queries.


    </details>


    <details>

    <summary><strong>Filter query parameter syntax</strong></summary>


    List endpoints that support a `filter` query parameter use a single string
    with **keys**, **operators**, and **combinators**. This keeps the number of
    query params small (AIP-160 style) while allowing flexible filtering.


    <details>

    <summary><strong>Operators</strong></summary>


    | Operator | Meaning    | Example            |

    | -------- | ---------- | ------------------ |

    | `=`      | Equals     | `chainId=1`        |

    | `!=`     | Not equals | `status!=REFUNDED` |


    </details>


    <details>

    <summary><strong>Combinators</strong></summary>


    | Combinator | Meaning                                      |
    Example                         |

    | ---------- | -------------------------------------------- |
    ------------------------------- |

    | `AND`      | All conditions must match (case-insensitive) | `chainId=1 AND
    name="Treasury"` |

    | `OR`       | Any condition may match (case-insensitive)   | `chainId=1 OR
    chainId=137`      |


    </details>


    <details>

    <summary><strong>Value formatting</strong></summary>


    | Type     | Use case                                  |
    Example                   |

    | -------- | ----------------------------------------- |
    ------------------------- |

    | Unquoted | Numbers, booleans, single-token values    | `chainId=1`,
    `valid=true` |

    | Quoted   | Strings with spaces or special characters | `name="Treasury
    Wallet"`  |

    | Escape   | Literal quote inside a quoted string      |
    `\"`                      |


    Allowed **keys** and **value types** (number, hex address, string, etc.) are
    defined per endpoint in the API docs and validated by the server.


    </details>


    <details>

    <summary><strong>Possible combinations (examples)</strong></summary>


    | Category              |
    Example                                             |

    | --------------------- |
    --------------------------------------------------- |

    | Single condition      |
    `chainId=1`                                         |

    | Single condition      |
    `status!=REFUNDED`                                  |

    | AND                   | `chainId=1 AND
    name="Treasury"`                     |

    | AND                   | `vaultAddress=0x123... AND
    chainId=1`               |

    | OR                    | `chainId=1 OR
    chainId=137`                          |

    | OR                    | `status=PENDING OR
    status=COMPLETE`                 |

    | Mixed AND and OR      | `chainId=1 AND (status=PENDING OR
    status=COMPLETE)` |

    | Equals and not-equals | `chainId=1 AND
    status!=REFUNDED`                    |

    | Equals and not-equals |
    `name!=""`                                          |


    Mixed AND and OR: AND has higher precedence; use parentheses for grouping.
    Without grouping, evaluation is left-to-right per implementation.


    </details>


    <details>

    <summary><strong>Implementation note</strong></summary>


    | Item      |
    Details                                                                   |

    | --------- |
    ------------------------------------------------------------------------- |

    | Location  |
    `src/common/utils/filter.util.ts`                                         |

    | Supported | `=`, `!=`, `AND`,
    `OR`                                                    |

    | Errors    | Invalid keys or value types return `400` with the standard
    error envelope |


    </details>


    </details>
  version: '2.0'
  contact: {}
servers:
  - url: https://api.paxoslabs.com/
    description: Production
security: []
tags: []
paths:
  /v1/paxg/swapQuotes:
    get:
      tags:
        - PAXG
      summary: Get PAXG swap quote
      description: >-
        Returns swap calldata for buying or selling PAXG via DEX aggregators.
        Supports Ethereum mainnet (chainId 1). The response includes the target
        contract, encoded calldata, and expected output amount.
      operationId: getPaxgSwapQuote
      parameters:
        - name: chainId
          required: true
          in: query
          description: 'EVM chain ID. Supported: 1 (Ethereum mainnet).'
          schema:
            example: 1
            type: number
            enum:
              - 1
        - name: offerAsset
          required: true
          in: query
          description: Token address to offer (sell).
          schema:
            example: '0x45804880De22913dAFE09f4980848ECE6EcbAf78'
            type: string
        - name: wantAsset
          required: true
          in: query
          description: Token address to receive (buy).
          schema:
            example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
            type: string
        - name: offerAmount
          required: true
          in: query
          description: Amount to offer, in the smallest unit of the token.
          schema:
            type: string
            example: '1000000000000000000'
        - name: userAddress
          required: true
          in: query
          description: Wallet address executing the swap.
          schema:
            example: '0x1234567890abcdef1234567890abcdef12345678'
            type: string
        - name: authMethod
          required: false
          in: query
          description: >-
            Authorization method. allowance_holder (recommended): standard
            approve flow. permit2: requires signing EIP-712 typed data.
          schema:
            default: allowance_holder
            example: allowance_holder
            type: string
            enum:
              - allowance_holder
              - permit2
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSwapQuoteResponseDto'
        '400':
          description: Invalid request parameters or insufficient liquidity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '503':
          description: DEX aggregator unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      security:
        - api-key: []
components:
  schemas:
    GetSwapQuoteResponseDto:
      type: object
      properties:
        transaction:
          $ref: '#/components/schemas/SwapQuoteTransactionDto'
        buyAmount:
          type: string
          description: Expected output amount in buy token wei.
          example: '2500000000'
        minBuyAmount:
          type: string
          description: >-
            Minimum acceptable output amount accounting for slippage. Use this
            to verify swap execution.
          example: '2475000000'
        allowanceTarget:
          type: string
          description: >-
            Contract address to approve tokens to before swapping.
            AllowanceHolder for default auth, Permit2 for permit2 auth.
          example: '0x0000000000001fF3684f28c67538d4D072C22734'
        currentAllowance:
          type: string
          description: >-
            User's current allowance for the allowanceTarget contract. If less
            than sellAmount, approval is needed.
          example: '0'
        permit2:
          description: >-
            Present when authMethod=permit2. Contains EIP-712 typed data to sign
            before executing the swap.
          allOf:
            - $ref: '#/components/schemas/Permit2DataDto'
      required:
        - transaction
        - buyAmount
        - minBuyAmount
        - allowanceTarget
    ErrorResponseDto:
      type: object
      properties:
        error:
          description: Error object containing details
          allOf:
            - $ref: '#/components/schemas/ErrorObjectDto'
      required:
        - error
    SwapQuoteTransactionDto:
      type: object
      properties:
        to:
          type: string
          description: Contract address to send the transaction to.
          example: '0x0d0e364aa7852291883c162b22d6d81f6355428f'
        data:
          type: string
          description: Encoded swap calldata.
          example: 0x...
        value:
          type: string
          description: ETH value to send (usually "0" for token sells).
          example: '0'
        gas:
          type: string
          description: Estimated gas limit for the transaction.
          example: '150000'
        gasPrice:
          type: string
          description: Suggested gas price in wei.
          example: '20000000000'
      required:
        - to
        - data
        - value
        - gas
        - gasPrice
    Permit2DataDto:
      type: object
      properties:
        type:
          type: string
          example: Permit2
        hash:
          type: string
          description: Hash to sign for Permit2 authorization.
          example: '0xafb2c83591d83ec04d0792eaa00d36f5a509dfab6666fa787e310afa276bf379'
        eip712:
          $ref: '#/components/schemas/Permit2Eip712Dto'
      required:
        - type
        - hash
        - eip712
    ErrorObjectDto:
      type: object
      properties:
        code:
          type: number
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: Invalid filter syntax.
        status:
          type: string
          description: Error status enum value
          enum:
            - UNKNOWN
            - INVALID_ARGUMENT
            - NOT_FOUND
            - PERMISSION_DENIED
            - UNAUTHENTICATED
            - RESOURCE_EXHAUSTED
            - INTERNAL
            - METHOD_NOT_ALLOWED
          example: INVALID_ARGUMENT
        details:
          description: Additional error details
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailDto'
      required:
        - code
        - message
        - status
    Permit2Eip712Dto:
      type: object
      properties:
        types:
          type: object
          description: EIP-712 type definitions
        domain:
          $ref: '#/components/schemas/Permit2DomainDto'
        message:
          $ref: '#/components/schemas/Permit2MessageDto'
        primaryType:
          type: string
          example: PermitTransferFrom
      required:
        - types
        - domain
        - message
        - primaryType
    ErrorDetailDto:
      type: object
      properties:
        '@type':
          type: string
          description: Type URL identifying the error detail schema
          example: type.paxoslabs.dev/errors/BadRequest
        fieldViolations:
          description: Field-level violations for validation errors
          type: array
          items:
            $ref: '#/components/schemas/FieldViolationDto'
      required:
        - '@type'
    Permit2DomainDto:
      type: object
      properties:
        name:
          type: string
          example: Permit2
        chainId:
          type: number
          example: 1
        verifyingContract:
          type: string
          example: '0x000000000022d473030f116ddee9f6b43ac78ba3'
      required:
        - name
        - chainId
        - verifyingContract
    Permit2MessageDto:
      type: object
      properties:
        permitted:
          $ref: '#/components/schemas/Permit2TokenPermissionsDto'
        spender:
          type: string
          example: '0x0d0e364aa7852291883c162b22d6d81f6355428f'
        nonce:
          type: string
          example: '2241959297937691820908574931991559'
        deadline:
          type: string
          example: '1739918089'
      required:
        - permitted
        - spender
        - nonce
        - deadline
    FieldViolationDto:
      type: object
      properties:
        field:
          type: string
          description: The field that caused the violation
          example: filter
        description:
          type: string
          description: Description of the violation
          example: vaultAddress 0x0x is an invalid hex address.
      required:
        - field
        - description
    Permit2TokenPermissionsDto:
      type: object
      properties:
        token:
          type: string
          example: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
        amount:
          type: string
          example: '1000000000000000000'
      required:
        - token
        - amount
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key in format: pxl_<public_id>_<secret>'

````