token.yaml

# yaml-language-server: $schema=https://meta.open-rpc.org/

$schema: https://meta.open-rpc.org/
openrpc: 1.2.4
info:
  title: Alchemy Private Transactions API JSON-RPC Specification
  description: A specification of the standard JSON-RPC methods for Private Transactions API.
  version: 0.0.0
servers:
  - url: https://eth-mainnet.g.alchemy.com/v2
    name: Ethereum Mainnet
  - url: https://eth-mainnetbeacon.g.alchemy.com/v2
    name: Ethereum Mainnet Beacon
  - url: https://eth-holesky.g.alchemy.com/v2
    name: Ethereum Holešky
  - url: https://eth-holeskybeacon.g.alchemy.com/v2
    name: Ethereum Holešky Beacon
  - url: https://eth-hoodi.g.alchemy.com/v2
    name: Ethereum Hoodi
  - url: https://eth-hoodibeacon.g.alchemy.com/v2
    name: Ethereum Hoodi Beacon
  - url: https://eth-sepolia.g.alchemy.com/v2
    name: Ethereum Sepolia
  - url: https://eth-sepoliabeacon.g.alchemy.com/v2
    name: Ethereum Sepolia Beacon
  - url: https://abstract-mainnet.g.alchemy.com/v2
    name: Abstract Mainnet
  - url: https://abstract-testnet.g.alchemy.com/v2
    name: Abstract Testnet
  - url: https://anime-mainnet.g.alchemy.com/v2
    name: Anime Mainnet
  - url: https://anime-sepolia.g.alchemy.com/v2
    name: Anime Sepolia
  - url: https://apechain-mainnet.g.alchemy.com/v2
    name: ApeChain Mainnet
  - url: https://apechain-curtis.g.alchemy.com/v2
    name: ApeChain Curtis
  - url: https://arb-mainnet.g.alchemy.com/v2
    name: Arbitrum Mainnet
  - url: https://arb-sepolia.g.alchemy.com/v2
    name: Arbitrum Sepolia
  - url: https://arbnova-mainnet.g.alchemy.com/v2
    name: Arbitrum Nova Mainnet
  - url: https://avax-mainnet.g.alchemy.com/v2
    name: Avalanche Mainnet
  - url: https://avax-fuji.g.alchemy.com/v2
    name: Avalanche Fuji
  - url: https://base-mainnet.g.alchemy.com/v2
    name: Base Mainnet
  - url: https://base-sepolia.g.alchemy.com/v2
    name: Base Sepolia
  - url: https://berachain-mainnet.g.alchemy.com/v2
    name: Berachain Mainnet
  - url: https://berachain-bepolia.g.alchemy.com/v2
    name: Berachain Bepolia
  - url: https://blast-mainnet.g.alchemy.com/v2
    name: Blast Mainnet
  - url: https://blast-sepolia.g.alchemy.com/v2
    name: Blast Sepolia
  - url: https://bnb-mainnet.g.alchemy.com/v2
    name: BNB Smart Chain Mainnet
  - url: https://bnb-testnet.g.alchemy.com/v2
    name: BNB Smart Chain Testnet
  - url: https://celo-mainnet.g.alchemy.com/v2
    name: Celo Mainnet
  - url: https://celo-sepolia.g.alchemy.com/v2
    name: Celo Sepolia
  - url: https://gensyn-testnet.g.alchemy.com/v2
    name: Gensyn Testnet
  - url: https://gnosis-mainnet.g.alchemy.com/v2
    name: Gnosis Mainnet
  - url: https://gnosis-chiado.g.alchemy.com/v2
    name: Gnosis Chiado
  - url: https://hyperliquid-mainnet.g.alchemy.com/v2
    name: Hyperliquid Mainnet
  - url: https://hyperliquid-testnet.g.alchemy.com/v2
    name: Hyperliquid Testnet
  - url: https://ink-mainnet.g.alchemy.com/v2
    name: Ink Mainnet
  - url: https://ink-sepolia.g.alchemy.com/v2
    name: Ink Sepolia
  - url: https://lens-mainnet.g.alchemy.com/v2
    name: Lens Mainnet
  - url: https://lens-sepolia.g.alchemy.com/v2
    name: Lens Sepolia
  - url: https://linea-mainnet.g.alchemy.com/v2
    name: Linea Mainnet
  - url: https://linea-sepolia.g.alchemy.com/v2
    name: Linea Sepolia
  - url: https://polygon-mainnet.g.alchemy.com/v2
    name: Polygon Mainnet
  - url: https://polygon-amoy.g.alchemy.com/v2
    name: Polygon Amoy
  - url: https://monad-mainnet.g.alchemy.com/v2
    name: Monad Mainnet
  - url: https://monad-testnet.g.alchemy.com/v2
    name: Monad Testnet
  - url: https://opt-mainnet.g.alchemy.com/v2
    name: OP Mainnet Mainnet
  - url: https://opt-sepolia.g.alchemy.com/v2
    name: OP Mainnet Sepolia
  - url: https://ronin-mainnet.g.alchemy.com/v2
    name: Ronin Mainnet
  - url: https://ronin-saigon.g.alchemy.com/v2
    name: Ronin Saigon
  - url: https://rootstock-mainnet.g.alchemy.com/v2
    name: Rootstock Mainnet
  - url: https://rootstock-testnet.g.alchemy.com/v2
    name: Rootstock Testnet
  - url: https://scroll-mainnet.g.alchemy.com/v2
    name: Scroll Mainnet
  - url: https://scroll-sepolia.g.alchemy.com/v2
    name: Scroll Sepolia
  - url: https://settlus-mainnet.g.alchemy.com/v2
    name: Settlus Mainnet
  - url: https://settlus-septestnet.g.alchemy.com/v2
    name: Settlus Sepolia
  - url: https://shape-mainnet.g.alchemy.com/v2
    name: Shape Mainnet
  - url: https://shape-sepolia.g.alchemy.com/v2
    name: Shape Sepolia
  - url: https://soneium-mainnet.g.alchemy.com/v2
    name: Soneium Mainnet
  - url: https://soneium-minato.g.alchemy.com/v2
    name: Soneium Minato
  - url: https://story-mainnet.g.alchemy.com/v2
    name: Story Mainnet
  - url: https://story-aeneid.g.alchemy.com/v2
    name: Story Aeneid
  - url: https://tea-sepolia.g.alchemy.com/v2
    name: Tea Sepolia
  - url: https://unichain-mainnet.g.alchemy.com/v2
    name: Unichain Mainnet
  - url: https://unichain-sepolia.g.alchemy.com/v2
    name: Unichain Sepolia
  - url: https://worldchain-mainnet.g.alchemy.com/v2
    name: World Chain Mainnet
  - url: https://worldchain-sepolia.g.alchemy.com/v2
    name: World Chain Sepolia
  - url: https://zetachain-mainnet.g.alchemy.com/v2
    name: ZetaChain Mainnet
  - url: https://zetachain-testnet.g.alchemy.com/v2
    name: ZetaChain Testnet
  - url: https://zksync-mainnet.g.alchemy.com/v2
    name: ZKsync Mainnet
  - url: https://zksync-sepolia.g.alchemy.com/v2
    name: ZKsync Sepolia
  - url: https://zora-mainnet.g.alchemy.com/v2
    name: Zora Mainnet
  - url: https://zora-sepolia.g.alchemy.com/v2
    name: Zora Sepolia
methods:
  - name: alchemy_getTokenAllowance
    description: Returns the token allowance by spender for a given owner.
    params:
      - name: tokenAllowanceRequest
        required: true
        description: >
          An object specifying the token contract address, the owner address, and
          the spender address.
        schema:
          type: object
          properties:
            contract:
              $ref: "../_shared/components.yaml#/components/schemas/address"
              description: "20-byte token contract address."
            owner:
              $ref: "../_shared/components.yaml#/components/schemas/address"
              description: "20-byte address of the owner."
            spender:
              $ref: "../_shared/components.yaml#/components/schemas/address"
              description: "20-byte address of the spender."
          required:
            - contract
            - owner
            - spender
    result:
      name: Allowance
      description: The amount that the spender is allowed to withdraw from the owner.
      schema:
        type: string
        description: A decimal string representing the allowance.
    examples:
      - name: Basic allowance example
        params:
          - name: tokenAllowanceRequest
            value:
              contract: "0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270"
              owner: "0xf1a726210550c306a9964b251cbcd3fa5ecb275d"
              spender: "0xdef1c0ded9bec7f1a1670819833240f027b25eff"
        result:
          name: Allowance
          value: "0"

  - name: alchemy_getTokenBalances
    description: Returns ERC-20 token balances for a given address.
    params:
      - name: address
        required: true
        description: >
          A 20-byte wallet address.
        schema:
          type: string
          title: Address
          default: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

      - name: tokenSpec
        required: false
        description: >
          A token specification:
          - The string "erc20"
          - "NATIVE_TOKEN" 
          - "DEFAULT_TOKENS" (deprecated)
          - An array of token contract addresses.
        schema:
          oneOf:
            - type: string
              title: "Token Specification"
              enum: ["erc20", "DEFAULT_TOKENS", "NATIVE_TOKEN"]
              default: "erc20"
            - type: array
              title: "Array of Contract Addresses"
              items:
                type: string
                pattern: "^0[xX][0-9a-fA-F]{40}$"

      - name: options
        required: false
        description: >
          Optional pagination options.
        schema:
          type: object
          title: "Options"
          properties:
            pageKey:
              type: string
              description: "Used for pagination if more results are available."
            maxCount:
              type: integer
              description: "Maximum number of token balances to return per call (capped at 100)."
              default: 100

    result:
      name: Token Balances
      description: An object containing the queried address and an array of token balance objects.
      schema:
        type: object
        properties:
          address:
            $ref: "../_shared/components.yaml#/components/schemas/address"
            description: "Address for which token balances were returned."
          tokenBalances:
            type: array
            description: "Array of token balance objects. Exactly one of tokenBalance or error is non-null."
            items:
              type: object
              properties:
                contractAddress:
                  $ref: "../_shared/components.yaml#/components/schemas/address"
                  description: "The ERC-20 contract address."
                tokenBalance:
                  type: string
                  description: "Hex-encoded string of the token balance, or null if error is present."

    examples:
      - name: Single token balance example
        params:
          - name: address
            value: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
          - name: tokenSpec
            value:
              - "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        result:
          name: Token Balances
          value:
            address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            tokenBalances:
              - contractAddress: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
                tokenBalance: "0x0000000000000000000000000000000000000000000000000000000000000000"

  - name: alchemy_getTokenMetadata
    description: Returns metadata for a given token contract (name, symbol, decimals, logo).
    params:
      - name: contractAddress
        required: true
        description: "A single 20-byte token contract address."
        schema:
          $ref: "../_shared/components.yaml#/components/schemas/address"
    result:
      name: Token Metadata
      description: Object with name, symbol, decimals, and an optional logo URL.
      schema:
        type: object
        properties:
          name:
            type: string
            description: "Token's name, or null if not found."
          symbol:
            type: string
            description: "Token's symbol, or null if not found."
          decimals:
            type: number
            description: "Number of decimals the token uses, or null if not found."
          logo:
            type: string
            description: "URL of the token's logo image, or null if none available."
    examples:
      - name: USDC metadata example
        params:
          - name: contractAddress
            value: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        result:
          name: Token Metadata
          value:
            name: "USD Coin"
            symbol: "USDC"
            decimals: 6
            logo: "https://static.alchemyapi.io/images/assets/3408.png"