Wormhole wormholescan API

openapi: 3.2.0
info:
  description: 'Wormhole Guardian API

    This is the API for the Wormhole Guardian and Explorer.

    The API has two namespaces: wormholescan and guardian.

    wormholescan is the namespace for the explorer and the new endpoints. The prefix is /api/v1.

    guardian is the legacy namespace backguard compatible with guardian node API. The prefix is /v1.

    This API is public and does not require authentication although some endpoints are rate limited.

    Check each endpoint documentation for more information.'
  title: Guardian Wormholescan API
  termsOfService: https://wormhole.com/
  contact:
    name: API Support
    url: https://discord.com/invite/wormholecrypto
    email: info@wormhole.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
servers:
- url: https://api.wormholescan.io/
tags:
- name: wormholescan
paths:
  /api/v1/address/:address:
    get:
      description: Lookup an address
      tags:
      - wormholescan
      operationId: find-address-by-id
      parameters:
      - description: address
        name: address
        in: path
        required: true
        schema:
          type: string
      - description: Page number. Starts at 0.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-address_AddressOverview'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /api/v1/application-activity:
    get:
      description: Search for a specific period of time the number of transactions and the volume per application.
      tags:
      - wormholescan
      operationId: application-activity
      parameters:
      - description: 'Time span, supported values: 1d, 1mo and 1y'
        name: timespan
        in: query
        required: true
        schema:
          type: string
      - description: From date, supported format 2006-01-02T15:04:05Z07:00
        name: from
        in: query
        required: true
        schema:
          type: string
      - description: To date, supported format 2006-01-02T15:04:05Z07:00
        name: to
        in: query
        required: true
        schema:
          type: string
      - description: Search by appId
        name: appIds
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/transactions.ChainActivityTopResult'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/global-tx/:chain_id/:emitter/:seq:
    get:
      description: 'Find a global transaction by VAA ID

        Global transactions is a logical association of two transactions that are related to each other by a unique VAA ID.

        The first transaction is created on the origin chain when the VAA is emitted.

        The second transaction is created on the destination chain when the VAA is redeemed.

        If the response only contains an origin tx the VAA was not redeemed.'
      tags:
      - wormholescan
      operationId: find-global-transaction-by-id
      parameters:
      - description: id of the blockchain
        name: chain_id
        in: path
        required: true
        schema:
          type: integer
      - description: address of the emitter
        name: emitter
        in: path
        required: true
        schema:
          type: string
      - description: sequence of the VAA
        name: seq
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transactions.Tx'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/config:
    get:
      description: Returns governor configuration for all guardians.
      tags:
      - wormholescan
      operationId: governor-config
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-governor_GovConfig'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/config/:guardian_address:
    get:
      description: Returns governor configuration for a given guardian.
      tags:
      - wormholescan
      operationId: governor-config-by-guardian-address
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-governor_GovConfig'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/enqueued_vaas/:
    get:
      description: Returns enqueued VAAs for each blockchain.
      tags:
      - wormholescan
      operationId: governor-enqueued-vaas
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_EnqueuedVaas'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/enqueued_vaas/:chain:
    get:
      description: Returns all enqueued VAAs for a given blockchain.
      tags:
      - wormholescan
      operationId: guardians-enqueued-vaas-by-chain
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_EnqueuedVaaDetail'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/limit:
    get:
      description: Returns the governor limit for all blockchains.
      tags:
      - wormholescan
      operationId: governor-notional-limit
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_GovernorLimit'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/notional/available:
    get:
      description: Returns the amount of notional value available for each blockchain.
      tags:
      - wormholescan
      operationId: governor-notional-available
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_NotionalAvailable'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/notional/available/:chain:
    get:
      description: Returns the amount of notional value available for a given blockchain.
      tags:
      - wormholescan
      operationId: governor-notional-available-by-chain
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_NotionalAvailableDetail'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/notional/limit:
    get:
      description: Returns the detailed notional limit for all blockchains.
      tags:
      - wormholescan
      operationId: governor-notional-limit-detail
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_NotionalLimitDetail'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/notional/limit/:chain:
    get:
      description: Returns the detailed notional limit available for a given blockchain.
      tags:
      - wormholescan
      operationId: governor-notional-limit-detail-by-chain
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_NotionalLimitDetail'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/notional/max_available/:chain:
    get:
      description: Returns the maximum amount of notional value available for a given blockchain.
      tags:
      - wormholescan
      operationId: governor-max-notional-available-by-chain
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-governor_MaxNotionalAvailableRecord'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/status:
    get:
      description: Returns the governor status for all guardians.
      tags:
      - wormholescan
      operationId: governor-status
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_GovStatus'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/status/:guardian_address:
    get:
      description: Returns the governor status for a given guardian.
      tags:
      - wormholescan
      operationId: governor-status-by-guardian-address
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-governor_GovStatus'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/governor/vaas:
    get:
      description: Returns all vaas in Governor.
      tags:
      - wormholescan
      operationId: governor-vaas
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-array_governor_GovernorVaasResponse'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/guardian_sets/{version}:
    get:
      description: Returns a guardian set by version, or the current one when "current" is supplied.
      tags:
      - wormholescan
      operationId: get-guardian-set
      parameters:
      - description: Guardian set version (uint32) or the literal \
        name: version
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.Response-guardian_sets_GuardianSetDoc'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /api/v1/health:
    get:
      description: Health check
      tags:
      - wormholescan
      operationId: health-check
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/last-txs:
    get:
      description: Returns the number of transactions by a defined time span and sample rate.
      tags:
      - wormholescan
      operationId: get-last-transactions
      parameters:
      - description: 'Time Span, default: 1d, supported values: [1d, 1w, 1mo]. 1mo ​​is 30 days.'
        name: timeSpan
        in: query
        schema:
          type: string
      - description: 'Sample Rate, default: 1h, supported values: [1h, 1d]. Valid configurations with timeSpan: 1d/1h, 1w/1d, 1mo/1d'
        name: sampleRate
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/transactions.TransactionCountResult'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/live-tracking/subscribe:
    get:
      description: Subscribe to live tracking events for a VAA or transaction
      tags:
      - wormholescan
      operationId: live-tracking-subscribe
      parameters:
      - description: VAA ID to track
        name: vaaID
        in: query
        schema:
          type: string
      - description: Transaction hash to track
        name: txHash
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workflow.Event'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/native-token-transfer/activity:
    get:
      description: Returns a list of values (tx count or notional) of the Native Token Transfer for a emitter and destination chains.
      tags:
      - wormholescan
      operationId: /api/v1/native-token-transfer/activity
      parameters:
      - description: Symbol of the native-token-transfer token.
        name: symbol
        in: query
        required: true
        schema:
          type: string
      - description: Renders the results using notional or tx count (default is notional).
        name: by
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/stats.NativeTokenTransferActivity'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/native-token-transfer/summary:
    get:
      description: Returns a summary of the Native Token Transfer.
      tags:
      - wormholescan
      operationId: /api/v1/native-token-transfer/summary
      parameters:
      - description: coingecko_id of the desired token.
        name: coingecko_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stats.NativeTokenTransferSummary'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/native-token-transfer/token-list:
    get:
      description: Returns the list of supported Native Token Transfer tokens.
      tags:
      - wormholescan
      operationId: /api/v1/native-token-transfer/token-list
      parameters:
      - description: Specify true/false if the response includes links.
        name: withLinks
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/stats.Token'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/native-token-transfer/top-address:
    get:
      description: Returns a list of values (tx count or notional) of the Native Token Transfer for address.
      tags:
      - wormholescan
      operationId: /api/v1/native-token-transfer/top-address
      parameters:
      - description: Symbol of the native-token-transfer token.
        name: symbol
        in: query
        required: true
        schema:
          type: string
      - description: Renders the results using notional or tx count (default is notional).
        name: by
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/stats.NativeTokenTransferTopAddress'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/native-token-transfer/top-holder:
    get:
      description: Returns a list of volume and chain of the Native Token Transfer for top holders.
      tags:
      - wormholescan
      operationId: /api/v1/native-token-transfer/top-holder
      parameters:
      - description: Coingecko_id of the native-token-transfer token.
        name: coingecko_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/stats.NativeTokenTransferTopHolder'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /api/v1/native-token-transfer/transfer-by-time:
    get:
      description: Returns a list of values (tx count or notional) of the Native Token Transfer for a emitter and destination chains.
      tags:
      - wormholescan
      operationId: /api/v1/native-token-transfer/transfer-by-time
      parameters:
      - description: From date, supported format 2006-01-02T15:04:05Z07:00
        name: from
        in: query
        required: true
        schema:
          type: string
      - description: To date, supported format 2006-01-02T15:04:05Z07:00
        name: to
        in: query
        required: true
        schema:
          type: string
      - description: Symbol of the native-token-transfer token.
        name: symbol
        in: query
        required: true
        schema:
          type: string
      - description: Renders the results using notional or tx count (default is notional).
        name: by
        in: query
        schema:
          type: string
      - description: 'Time Span, supported values: [1h, 1d, 1mo, 1y].'
        name: timeSpan
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/stats.NativeTokenTransferByTime'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/observations:
    get:
      description: Returns all observations, sorted in descending timestamp order.
      tags:
      - wormholescan
      operationId: find-observations
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Transaction hash of the Observations
        name: txHash
        in: query
        schema:
          type: string
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/observations.ObservationDoc'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/observations/:chain:
    get:
      description: Returns all observations for a given blockchain, sorted in descending timestamp order.
      tags:
      - wormholescan
      operationId: find-observations-by-chain
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/observations.ObservationDoc'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/observations/:chain/:emitter:
    get:
      description: Returns all observations for a specific emitter address, sorted in descending timestamp order.
      tags:
      - wormholescan
      operationId: find-observations-by-emitter
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/observations.ObservationDoc'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/observations/:chain/:emitter/:sequence:
    get:
      description: Find observations identified by emitter chain, emitter address and sequence.
      tags:
      - wormholescan
      operationId: find-observations-by-sequence
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/observations.ObservationDoc'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/observations/:chain/:emitter/:sequence/:signer/:hash:
    get:
      description: Find a specific observation.
      tags:
      - wormholescan
      operationId: find-observations-by-id
      parameters:
      - description: Page number.
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page.
        name: pageSize
        in: query
        schema:
          type: integer
      - description: Sort results in ascending or descending order.
        name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/observations.ObservationDoc'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
  /api/v1/observations/delegate/:chain_id:
    get:
      description: Returns delegate observations for a given chain, sorted in descending timestamp order.
      tags:
      - wormholescan
      operationId: find-delegate-observations-by-chain
      parameters:
      - description: Chain ID
        name: chain_id
        in: path
        required: true
        schema:
          type: integer
      - description: Page number
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page
        name: pageSize
        in: query
        schema:
          type: integer
      - description: ASC or DESC
        name: sortOrder
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/delegate_observations.DelegateObservationDoc'
  /api/v1/observations/delegate/:chain_id/:emitter_address:
    get:
      description: Returns delegate observations for a given chain and emitter, sorted in descending timestamp order.
      tags:
      - wormholescan
      operationId: find-delegate-observations-by-emitter
      parameters:
      - description: Chain ID
        name: chain_id
        in: path
        required: true
        schema:
          type: integer
      - description: Emitter address
        name: emitter_address
        in: path
        required: true
        schema:
          type: string
      - description: Page number
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page
        name: pageSize
        in: query
        schema:
          type: integer
      - description: ASC or DESC
        name: sortOrder
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/delegate_observations.DelegateObservationDoc'
  /api/v1/observations/delegate/:chain_id/:emitter_address/:sequence:
    get:
      description: Returns delegate observations for a given chain, emitter and sequence.
      tags:
      - wormholescan
      operationId: find-delegate-observations-by-sequence
      parameters:
      - description: Chain ID
        name: chain_id
        in: path
        required: true
        schema:
          type: integer
      - description: Emitter address
        name: emitter_address
        in: path
        required: true
        schema:
          type: string
      - description: Sequence
        name: sequence
        in: path
        required: true
        schema:
          type: integer
      - description: Page number
        name: page
        in: query
        schema:
          type: integer
      - description: Number of elements per page
        name: pageSize
        in: query
        schema:
          type: integer
      - description: ASC or DESC
        name: sortOrder
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/delegate_observations.DelegateObservationDoc'
  /api/v1/observations/delegate/:chain_id/:emitter_address/:sequence/:guardian_address:
    get:
      description: Returns delegate observations for a given chain, emitter, sequence and delegate guardian address.
      tags:
      - wormholescan
      operationId: find-delegate-observations-by-guardian
      parameters:
      - description: Chain ID
        name: chain_id
        in: path
        required: true
        schema:
          type: integer
      - description: Emitter address
        name: emitter_address
 

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