Halliday API V2

openapi: 3.1.0
info:
  title: Halliday API V2
  description: >
    API V2 for Halliday's payment infrastructure, supporting onramps, swaps, and
    offramps.


    This API provides a unified interface for cryptocurrency payments, allowing
    developers to:

    - Quote payments across multiple providers

    - Execute payments with onramps, swaps, and offramps

    - Track payment status and history


    ## Authentication


    API key authentication is required for all endpoints.
  version: 2.0.0
  contact:
    name: Contact Halliday
    url: https://halliday.xyz
    email: support@halliday.xyz
security:
  - ApiKeyAuth: []
servers:
  - url: https://v2.prod.halliday.xyz
    description: Base domain
paths:
  /chains:
    get:
      summary: Get supported chains
      description: >
        Get a list of all supported blockchain networks with their configuration
        details.
      operationId: getChains
      tags:
        - Chains
      responses:
        '200':
          description: List of supported chains
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ChainInfo'
              example:
                ethereum:
                  chain_id:
                    \#: 1
                  network: ethereum
                  native_currency:
                    name: Ether
                    symbol: ETH
                    decimals: 18
                  is_testnet: false
                  explorer: https://etherscan.io/
                  image: <IMAGE_URL>...
                  rpc: <RPC_URL>...
                arbitrum:
                  chain_id:
                    \#: 42161
                  network: arbitrum
                  native_currency:
                    name: Ether
                    symbol: ETH
                    decimals: 18
                  is_testnet: false
                  explorer: https://arbiscan.io/
                  image: <IMAGE_URL>...
                  rpc: <RPC_URL>...
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Insufficient permissions to access this resource
  /assets:
    get:
      summary: Get asset details
      description: >
        Get detailed information about specific assets including metadata,
        symbols, and chain information.
      operationId: getAssets
      tags:
        - Assets
      parameters:
        - name: assets[]
          in: query
          required: false
          description: List of assets to get details for
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Asset'
      responses:
        '200':
          description: Asset details
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/AssetDetails'
              example:
                usd:
                  issuer: USA
                  name: United States Dollar
                  symbol: USD
                  decimals: 2
                eur:
                  issuer: ECB
                  name: Euro
                  symbol: EUR
                  decimals: 2
                ethereum:0x:
                  chain: ethereum
                  address: 0x
                  name: Ether
                  symbol: ETH
                  decimals: 18
                  image_url: >-
                    https://coin-images.coingecko.com/coins/images/279/large/ethereum.png?1696501628
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      Invalid asset format. Expected format: 'chain:address' for
                      tokens or currency code for fiats
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Missing or invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      API key does not have permission to access asset
                      information
  /assets/available-inputs:
    get:
      summary: Get available input assets for a given output asset
      description: >
        Get a list of assets that can be used as inputs for the given output
        assets and providers.
      operationId: getInputAssets
      tags:
        - Assets
      parameters:
        - name: inputs[]
          in: query
          required: false
          description: Filter by specific input assets
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Asset'
        - name: outputs[]
          in: query
          required: false
          description: Output assets to find inputs for
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Asset'
        - name: onramps[]
          in: query
          required: false
          description: Filter by specific onramp providers
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: offramps[]
          in: query
          required: false
          description: Filter by specific offramp providers
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Available input assets grouped by output
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    fiats:
                      type: array
                      items:
                        $ref: '#/components/schemas/Fiat'
                    tokens:
                      type: array
                      items:
                        $ref: '#/components/schemas/Token'
                  required:
                    - fiats
                    - tokens
              example:
                ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48:
                  fiats:
                    - usd
                  tokens: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      Invalid provider specified. Provider 'invalid_provider' is
                      not supported
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Authentication required. Please provide a valid API key.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      Access denied. Your API key does not have permission to
                      query available assets.
  /assets/available-outputs:
    get:
      summary: Get available output assets for a given input asset
      description: >
        Get a list of assets that can be received as outputs for the given input
        assets and providers.
      operationId: getOutputAssets
      tags:
        - Assets
      parameters:
        - name: inputs[]
          in: query
          required: false
          description: Input assets to find outputs for
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Asset'
        - name: outputs[]
          in: query
          required: false
          description: Filter by specific output assets
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Asset'
        - name: onramps[]
          in: query
          required: false
          description: Filter by specific onramp providers
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: offramps[]
          in: query
          required: false
          description: Filter by specific offramp providers
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: features[]
          in: query
          required: false
          description: Feature flags to enable additional asset edges
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - BETA_EDGES
                - ORG_BETA_EDGES
                - ORG_EDGES
      responses:
        '200':
          description: Available output assets grouped by input
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    fiats:
                      type: array
                      items:
                        $ref: '#/components/schemas/Fiat'
                    tokens:
                      type: array
                      items:
                        $ref: '#/components/schemas/Token'
                  required:
                    - fiats
                    - tokens
              example:
                usd:
                  fiats: []
                  tokens:
                    - arbitrum:0x
                    - ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      Invalid input asset format. Asset 'invalid-format' does
                      not match expected pattern.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid or expired API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Your account does not have access to this endpoint
  /payments:
    get:
      summary: Get payment status
      description: >
        Get the current status of a payment, including progress through
        onramp/swap/offramp stages.
      operationId: getPaymentStatus
      tags:
        - Payments
      parameters:
        - name: payment_id
          in: query
          required: true
          description: Payment identifier to check
          schema:
            type: string
      responses:
        '200':
          description: Payment status retrieved successfully!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: 'Missing required parameter: payment_id'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: You do not have permission to view this payment
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Payment with payment_id 'pay_abc123' not found
  /payments/history:
    get:
      summary: Get payment history
      description: >
        Retrieve a paginated list of payment statuses filtered by owner.

        Returns an array of payment status objects and a pagination key for
        fetching the next page.
      operationId: getPaymentHistory
      tags:
        - Payments
      parameters:
        - name: owner_address
          in: query
          required: false
          description: Owner address to filter payments by
          schema:
            type: string
        - name: pagination_key
          in: query
          required: false
          description: Pagination key from previous response to fetch next page
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: number
        - name: id_query
          in: query
          required: false
          description: Filter payments by ID
          schema:
            type: string
        - name: dest_address
          in: query
          required: false
          description: Filter payments by destination address
          schema:
            type: string
        - name: category
          in: query
          required: false
          description: Filter payments by category
          schema:
            type: string
            enum:
              - ALL
              - NEW_OR_FUNDED
            default: NEW_OR_FUNDED
        - name: label
          in: query
          required: false
          description: Filter payments by label
          schema:
            type: string
      responses:
        '200':
          description: Payment history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - payment_statuses
                  - next_pagination_key
                properties:
                  payment_statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentStatus'
                    description: Array of payment status objects
                  next_pagination_key:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Pagination key to fetch the next page of results
                    example: >-
                      42ff9b02-037f-4a90-87fb-a4d2ca128565_2025-11-12T22:08:52.517Z
              example:
                payment_statuses:
                  - payment_id: <string>
                    status: COMPLETE
                    funded: true
                    created_at: '2025-11-12T20:15:30.000Z'
                    updated_at: '2025-11-12T20:25:45.000Z'
                    initiate_fund_by: '2025-11-12T21:15:30.000Z'
                    completed_at: '2025-11-12T20:25:45.000Z'
                    quoted:
                      output_amount:
                        asset: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                        amount: '100.00'
                      fees:
                        total_fees: '3.50'
                        conversion_fees: '2.00'
                        network_fees: '1.00'
                        business_fees: '0.50'
                        currency_symbol: USD
                      onramp: stripe
                      onramp_method: credit_card
                      route:
                        - type: ONRAMP
                          net_effect:
                            consume:
                              - account: USER
                                resource:
                                  asset: usd
                                  property: BALANCE
                                amount:
                                  amount: '103.50'
                            produce:
                              - account: PROCESSING_ADDRESS
                                resource:
                                  asset: >-
                                    ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                                  property: BALANCE
                                amount:
                                  amount: '100.00'
                          pieces_info:
                            - type: onramp
                          step_index: 0
                    fulfilled:
                      output_amount:
                        asset: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                        amount: '100.00'
                      fees:
                        total_fees: '3.50'
                        conversion_fees: '2.00'
                        network_fees: '1.00'
                        business_fees: '0.50'
                        currency_symbol: USD
                      onramp: stripe
                      onramp_method: credit_card
                      route:
                        - status: COMPLETE
                          type: ONRAMP
                          net_effect:
                            consume:
                              - account: USER
                                resource:
                                  asset: usd
                                  property: BALANCE
                                amount:
                                  amount: '103.50'
                            produce:
                              - account: PROCESSING_ADDRESS
                                resource:
                                  asset: >-
                                    ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                                  property: BALANCE
                                amount:
                                  amount: '100.00'
                          pieces_info:
                            - type: onramp
                          step_index: 0
                          transaction_hash: >-
                            0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                    current_prices:
                      USD: '1.00'
                      ethereum:0x: '4200.00'
                      ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48: '1.00'
                    price_currency: USD
                    processing_addresses:
                      - chain: ethereum
                        address: 0xaddress...
                    owner_address: 0xowner...
                    destination_address: 0xdest...
                next_pagination_key: 42ff9b02-037f-4a90-87fb-a4d2ca128565_2025-11-12T22:08:52.517Z
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: 'Missing required parameter: owner_address'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      You do not have permission to access payment history for
                      this address
  /payments/quotes:
    post:
      summary: Get payment quotes
      description: >
        Request quotes for payments, supporting both fixed input and fixed
        output scenarios.

        Returns multiple quote options with pricing, fees, and routing
        information.


        This endpoint can also be used to requote from an existing payment by
        providing a payment_id.

        When requoting, input amounts are automatically derived from

        the payment's current state, but you can optionally override the output
        asset.
      operationId: getPaymentQuotes
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: Successful quote response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: amount
                    given: '5'
                    limits:
                      min: '10'
                      max: '10000'
                    source: moonpay
                    message: Amount too low. Minimum amount is $10 USD
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: API key missing or invalid
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Your API key does not have permission to create quotes
  /payments/confirm:
    post:
      summary: Confirm a payment
      description: >
        Confirm a previously quoted payment and receive deposit instructions.

        Returns information on how to fund the payment (widget URL, contract
        address, etc.).


        If a payment output is >= $300 USD, the owner address will need to
        produce a EVM_OWNER

        signature. The response will include a USER_VERIFY next_instruction
        instead of funding

        details. In this case, prompt the user to sign the verification payloads
        via signTypedData,

        then submit a ContinueConfirmPaymentRequest to this same endpoint to
        complete confirmation.

        Once an owner address has produced an EVM_OWNER signature, subsequent
        payments with that

        owner address will not require the signature again.
      operationId: confirmPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: ConfirmPaymentRequest
                  description: Initial payment confirmation request.
                  type: object
                  required:
                    - payment_id
                    - state_token
                    - owner_address
                    - destination_address
                  properties:
                    payment_id:
                      type: string
                      description: ID of the payment from the quote to confirm
                    state_token:
                      type: string
                      description: State token from the quote response
                    owner_address:
                      type: string
                      description: >-
                        Owner address for the payment. This is the address that
                        the payment will be sent from.
                    destination_address:
                      type: string
                      description: >-
                        Destination address for the payment. This is the address
                        that the payment will be sent to.
                    client_redirect_url:
                      type: string
                      format: uri
                      description: >-
                        Optional URL to redirect users to after an onramp flow
                        completes.
                    owner_chain:
                      type: string
                      description: >-
                        Optional chain for the owner address, needed when the
                        owner operates on a specific chain.
                    client_redirect_after:
                      type: string
                      enum:
                        - COMPLETED
                        - FUNDED
                      default: COMPLETED
                      description: >-
                        When to redirect the user to the client_redirect_url.
                        COMPLETED waits for the full payment to finish, FUNDED
                        redirects after funding is confirmed.
                - title: ContinueConfirmPaymentRequest
                  description: >
                    Continuation request after a USER_VERIFY instruction. Submit
                    the signed verification

                    payloads to complete the confirmation process.
                  type: object
                  required:
                    - verification_token
                    - signatures
                  properties:
                    verification_token:
                      type: string
                      description: >-
                        Opaque HMAC-signed token from the USER_VERIFY
                        instruction. Pass back unmodified.
                    signatures:
                      type: array
                      description: >-
                        User-signed payloads, one per verification entry from
                        the USER_VERIFY instruction.
                      items:
                        type: object
                        required:
                          - reason
                          - signature_type
                          - signature
                        properties:
                          reason:
                            type: string
                            enum:
                              - EVM_OWNER
                              - EVM_WITHDRAWAL
                            description: >-
                              Must match the reason from the corresponding
                              verification entry.
                          signature_type:
                            type: string
                            enum:
                              - EIP712
                            description: >-
                              Must match the signature_type from the
                              corresponding verification entry.
                          signature:
                            type: string
                            description: >-
                              The user's signature over the verification
                              payload.
      responses:
        '200':
          description: Payment confirmed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid state_token. The quote may have expired.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Authentication failed. Invalid API key.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: >-
                      Access denied. This payment belongs to a different
                      account.
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Payment 'pay_xyz789' not found or has expired
  /payments/withdraw:
    post:
      summary: Return funds to owner or retry payment
      description: >
        Request a withdrawal to return funds back to the owner or to a requoted
        processing address.

        This endpoint should be used when a payment cannot be completed and
        funds need to be returned.
      operationId: withdrawPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawPaymentAuthorizationRequest'
      responses:
        '200':
          description: Withdrawal initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawPaymentAuthorizationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Missing field 'token_amounts'.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid or missing API key
        '403':
          description: Forbidden
          content:
            application/js

# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/halliday/refs/heads/main/openapi/halliday-openapi-original.yml