Arkham History API

openapi: 3.2.0
info:
  title: Arkham History API
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged History across 2 of this provider''s published API definitions: arkham-openapi-original.json, arkham-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.arkm.com/x402
tags:
- name: History
paths:
  /history/address/{address}:
    get:
      summary: Get historical data for an address
      description: Returns a daily USD value time series for the specified address.
      operationId: GetAddressHistory
      parameters:
      - name: chains
        in: query
        description: Chains to filter by, as a single comma-separated value (e.g. 'ethereum,bsc'). If omitted, returns data across all supported chains.
        schema:
          $ref: '#/components/schemas/Chains'
      - name: address
        in: path
        description: The blockchain address to query historical data for.
        required: true
        schema:
          type: string
          description: The blockchain address to query historical data for.
          example: '0x28C6c06298d514Db089934071355E5743bf21d60'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/HistorySnapshot'
                  example:
                  - time: '2024-01-01T00:00:00Z'
                    usd: 1.23
                example:
                  bsc:
                  - time: '2023-12-13T00:00:00Z'
                    usd: 2844820.37
                  - time: '2023-12-14T00:00:00Z'
                    usd: 3174696.58
                  ethereum:
                  - time: '2023-11-29T00:00:00Z'
                    usd: 2524608983.37
                  - time: '2023-11-30T00:00:00Z'
                    usd: 2535428111.78
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      tags:
      - History
  /history/entity/{entity}:
    get:
      summary: Get historical data for an entity
      description: Returns a daily USD value time series for the specified entity.
      operationId: GetEntityHistory
      parameters:
      - name: chains
        in: query
        description: Chains to filter by, as a single comma-separated value (e.g. 'ethereum,bitcoin'). If omitted, returns data across all supported chains.
        schema:
          $ref: '#/components/schemas/Chains'
      - name: entity
        in: path
        description: The entity ID to query historical data for.
        required: true
        schema:
          type: string
          description: The entity ID to query historical data for.
          example: binance
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/HistorySnapshot'
                  example:
                  - time: '2024-01-01T00:00:00Z'
                    usd: 1.23
                example:
                  bitcoin:
                  - time: '2022-01-22T00:00:00Z'
                    usd: 19480915256.37
                  - time: '2022-01-23T00:00:00Z'
                    usd: 18645267553.47
                  ethereum:
                  - time: '2021-12-31T00:00:00Z'
                    usd: 51606841219.03
                  - time: '2022-01-01T00:00:00Z'
                    usd: 51120113947.47
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      tags:
      - History
  /history/address:
    post:
      operationId: history_address
      summary: Get Arkham historical data for an address
      tags:
      - History
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.20'
        protocols:
        - x402: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  anyOf:
                  - type: string
                  - type: number
                  - type: boolean
                  - type: array
                    items:
                      anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                  description: The blockchain address to query historical data for.
                chains:
                  description: Chains to filter by, as a single comma-separated value (e.g. 'ethereum,bsc'). If omitted, returns data across all suppo…
                  anyOf:
                  - type: string
                  - type: number
                  - type: boolean
                  - type: array
                    items:
                      anyOf:
                      - type: string
                      - type: number
                      - type: boolean
              required:
              - address
              additionalProperties:
                anyOf:
                - type: string
                - type: number
                - type: boolean
                - type: array
                  items:
                    anyOf:
                    - type: string
                    - type: number
                    - type: boolean
            example:
              address: '0x28C6c06298d514Db089934071355E5743bf21d60'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: {}
        '400':
          $ref: '#/components/responses/BadRequest400'
        '402':
          $ref: '#/components/responses/PaymentRequired402'
        '404':
          $ref: '#/components/responses/NotFound404'
        '429':
          $ref: '#/components/responses/RateLimited429'
        5XX:
          $ref: '#/components/responses/UpstreamError5xx'
      security: []
      description: Get Arkham historical data for an address. $0.20 per call.
    servers:
    - url: https://api.arkm.com/x402
  /history/entity:
    post:
      operationId: history_entity
      summary: Get Arkham historical data for an entity
      tags:
      - History
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.40'
        protocols:
        - x402: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entity:
                  anyOf:
                  - type: string
                  - type: number
                  - type: boolean
                  - type: array
                    items:
                      anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                  description: The entity ID to query historical data for. IDs are case-sensitive; look one up with GET /intelligence/search.
                chains:
                  description: Chains to filter by, as a single comma-separated value (e.g. 'ethereum,bitcoin'). If omitted, returns data across all s…
                  anyOf:
                  - type: string
                  - type: number
                  - type: boolean
                  - type: array
                    items:
                      anyOf:
                      - type: string
                      - type: number
                      - type: boolean
              required:
              - entity
              additionalProperties:
                anyOf:
                - type: string
                - type: number
                - type: boolean
                - type: array
                  items:
                    anyOf:
                    - type: string
                    - type: number
                    - type: boolean
            example:
              entity: binance
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema: {}
        '400':
          $ref: '#/components/responses/BadRequest400'
        '402':
          $ref: '#/components/responses/PaymentRequired402'
        '404':
          $ref: '#/components/responses/NotFound404'
        '429':
          $ref: '#/components/responses/RateLimited429'
        5XX:
          $ref: '#/components/responses/UpstreamError5xx'
      security: []
      description: Get Arkham historical data for an entity. $0.40 per call.
    servers:
    - url: https://api.arkm.com/x402
components:
  schemas:
    Chains:
      type: array
      items:
        $ref: '#/components/schemas/Chain'
      example:
      - ethereum
      - bsc
      - polygon
    Chain:
      enum:
      - ethereum
      - polygon
      - bsc
      - optimism
      - avalanche
      - arbitrum_one
      - base
      - bitcoin
      - tron
      - flare
      - solana
      - dogecoin
      - zcash
      - hyperevm
      - hypercore
      type: string
      example: ethereum
    HistorySnapshot:
      required:
      - time
      - usd
      type: object
      properties:
        time:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
        usd:
          type: number
          example: 1.23
      example:
        time: '2024-01-01T00:00:00Z'
        usd: 1.23
  responses:
    PaymentRequired402:
      description: 'Payment challenge, not an application error. Read the base64 x402 v2 challenge from PAYMENT-REQUIRED, sign it, and retry the same request with PAYMENT-SIGNATURE. If a post-payment 402 omits PAYMENT-REQUIRED, verification failed: read the new challenge, re-sign, and retry once.'
      headers:
        PAYMENT-REQUIRED:
          description: Base64-encoded x402 v2 payment requirements. Its accepts array contains the scheme, network, asset, atomic amount, and payTo address.
          schema:
            type: string
    NotFound404:
      description: The upstream Arkham resource does not exist. Fatal for the same input. Payment is not settled.
    UpstreamError5xx:
      description: Arkham failed or timed out, including 502 and 504 responses. Retry with backoff. x402 payments and MPP transaction credentials are not settled for failed requests; MPP hash credits are redeemed at admission and are not refunded automatically.
    RateLimited429:
      description: Per-wallet endpoint rate limit exceeded. Retry with at least 1 second of backoff; keep heavy endpoints at no more than 5 requests per second.
    BadRequest400:
      description: 'Fatal for the request as written: validation failed or required JSON body fields are missing. Fix the request; do not retry it unchanged. Payment is not settled.'
      content:
        application/json:
          schema:
            type: object
            required:
            - success
            - error
            properties:
              success:
                type: boolean
                enum:
                - false
              error:
                type: string
              issues:
                type: array
                description: Per-field validation issues, present when schema validation produced them.
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
x-refined-from:
- arkham-openapi-original.json
- arkham-openapi.json