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

# Get geolocation for an IP address

> Resolve an IP address to a country, region, and default fiat currency. Pass the end user's
`customer_ip_address` when your backend makes the request on their behalf; when omitted, the
IP address of the request itself is used.

Onramp provider and payment method availability depend on the user's location, so use this to
pick a default fiat currency before quoting and to confirm which location the
`customer_ip_address` you pass to `POST /payments/quotes` resolves to.




## OpenAPI

````yaml /public/openapi.yaml get /geolocation
openapi: 3.1.0
info:
  title: Halliday
  description: >
    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
servers:
  - url: https://v2.prod.halliday.xyz
    description: Base domain
security:
  - ApiKeyAuth: []
tags:
  - name: Chains
    description: Blockchain network information and configuration
  - name: Assets
    description: Asset information, discovery, and supported asset pairs
  - name: Geolocation
    description: >-
      Resolve an end user's IP address to a location and default fiat currency
      before quoting
  - name: Prices
    description: Current token prices denominated in a fiat currency
  - name: Payments
    description: >-
      Core payment operations including quotes, confirmation, and status
      tracking
  - name: Webhooks
    description: >
      Register HTTPS endpoints to receive signed notifications when a workflow
      reaches a terminal

      state, instead of polling for status. You subscribe to one or more event
      types per webhook.


      | Event type | Fires when a workflow's status becomes |

      | --- | --- |

      | `WORKFLOW_COMPLETED` | `COMPLETE` |

      | `WORKFLOW_FAILED` | `FAILED` |


      All management endpoints live under `/orgs/webhooks` and authenticate with
      a secret API key

      (passed as a bearer token) that has webhook access. Publishable keys
      cannot manage webhooks.


      **Integration checklist**


      - Receiver is a public HTTPS endpoint (no private IPs).

      - Save the `signing_secret` when you create the webhook — it is shown only
      once.

      - Verify `X-Halliday-Signature` against the raw body, accepting any of its
      comma-separated signatures.

      - Respond `2xx` quickly and do the real work afterward.

      - Skip deliveries whose `id` you have already handled.
paths:
  /geolocation:
    get:
      tags:
        - Geolocation
      summary: Get geolocation for an IP address
      description: >
        Resolve an IP address to a country, region, and default fiat currency.
        Pass the end user's

        `customer_ip_address` when your backend makes the request on their
        behalf; when omitted, the

        IP address of the request itself is used.


        Onramp provider and payment method availability depend on the user's
        location, so use this to

        pick a default fiat currency before quoting and to confirm which
        location the

        `customer_ip_address` you pass to `POST /payments/quotes` resolves to.
      operationId: getGeolocation
      parameters:
        - name: customer_ip_address
          in: query
          required: false
          description: >-
            IPv4 or IPv6 address of the end user. Defaults to the IP address of
            the request.
          schema:
            type: string
          example: 8.8.8.8
      responses:
        '200':
          description: Geolocation resolved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationResponse'
              example:
                alpha3_country_code: USA
                state_code: PA
                default_currency: USD
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                errors:
                  - code: invalid_union
                    path:
                      - customer_ip_address
                    message: Invalid input
      security: []
components:
  schemas:
    GeolocationResponse:
      anyOf:
        - type: object
          required:
            - alpha3_country_code
            - state_code
          properties:
            alpha3_country_code:
              type: string
              description: ISO 3166-1 alpha-3 country code
              example: USA
            state_code:
              type: string
              description: Two-letter region code, or an empty string when not available
              example: PA
            default_currency:
              type: string
              description: Default fiat currency code for the location
              example: USD
        - type: 'null'
      description: Resolved location, or null if the IP address could not be resolved
    ValidationErrorResponse:
      type: object
      description: >
        Returned when a request body fails schema validation. `errors` contains
        one entry per

        validation issue.
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - code
              - path
              - message
            properties:
              code:
                type: string
                description: Validation issue code (for example `invalid_type`).
                example: invalid_type
              expected:
                type: string
                description: Expected type. Present on type-mismatch issues.
                example: string
              path:
                type: array
                description: Path to the offending field in the request body.
                items:
                  type:
                    - string
                    - integer
                example:
                  - label
              message:
                type: string
                example: 'Invalid input: expected string, received undefined'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.