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

# Price API

> Use AKKA as a real-time token price feed on HyperEVM

AKKA aggregates liquidity across every DEX on HyperEVM. As a side effect, the token endpoints provide real-time USD prices derived from actual pool reserves — not a single source, but a volume-weighted view across all indexed markets.

## Get all token prices in one call

Fetch the full token list to get prices for every token on the chain:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "apikey: YOUR_API_KEY" \
    "https://api.akka.finance/999/tokens?verified=true"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    'https://api.akka.finance/999/tokens?verified=true',
    { headers: { apikey: 'YOUR_API_KEY' } }
  );
  const { tokens } = await res.json();

  // tokens is a map: { [address]: { symbol, buyPriceUsd, sellPriceUsd, ... } }
  for (const [address, token] of Object.entries(tokens)) {
    console.log(`${token.symbol}: $${token.buyPriceUsd}`);
  }
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.akka.finance/999/tokens",
      params={"verified": "true"},
      headers={"apikey": "YOUR_API_KEY"},
  )
  tokens = res.json()["tokens"]

  for address, token in tokens.items():
      print(f"{token['symbol']}: ${token['buyPriceUsd']}")
  ```
</CodeGroup>

Each token includes two price fields:

| Field          | Description                                            |
| -------------- | ------------------------------------------------------ |
| `buyPriceUsd`  | Cost to buy 1 unit of this token (USD)                 |
| `sellPriceUsd` | Value received when selling 1 unit of this token (USD) |

The spread between `buyPriceUsd` and `sellPriceUsd` reflects real market liquidity — tighter spreads indicate deeper liquidity.

## Get a single token price

If you only need the price for one token:

```bash theme={null}
curl -H "apikey: YOUR_API_KEY" \
  "https://api.akka.finance/999/tokens/0x5555555555555555555555555555555555555555"
```

```json theme={null}
{
  "symbol": "WHYPE",
  "name": "Wrapped HYPE",
  "decimals": 18,
  "address": "0x5555555555555555555555555555555555555555",
  "verified": true,
  "buyPriceUsd": 25.42,
  "sellPriceUsd": 25.38
}
```

## Price polling pattern

Prices are refreshed every \~5 seconds on the backend. For most use cases, polling every 15–30 seconds is sufficient and stays well within the rate limit.

```typescript priceService.ts theme={null}
const API_BASE = 'https://api.akka.finance';
const API_KEY = process.env.AKKA_API_KEY!;
const POLL_INTERVAL = 15_000; // 15 seconds

interface TokenPrice {
  symbol: string;
  address: string;
  buyPriceUsd: number | null;
  sellPriceUsd: number | null;
}

let priceCache = new Map<string, TokenPrice>();

async function refreshPrices(): Promise<void> {
  const res = await fetch(
    `${API_BASE}/999/tokens?verified=true`,
    { headers: { apikey: API_KEY } },
  );
  const { tokens } = await res.json();

  const updated = new Map<string, TokenPrice>();
  for (const [address, token] of Object.entries(tokens) as [string, any][]) {
    updated.set(address.toLowerCase(), {
      symbol: token.symbol,
      address: token.address,
      buyPriceUsd: token.buyPriceUsd,
      sellPriceUsd: token.sellPriceUsd,
    });
  }
  priceCache = updated;
}

// Start polling
refreshPrices();
setInterval(refreshPrices, POLL_INTERVAL);

// Read from cache (instant, no API call)
export function getPrice(tokenAddress: string): TokenPrice | undefined {
  return priceCache.get(tokenAddress.toLowerCase());
}

export function getAllPrices(): Map<string, TokenPrice> {
  return priceCache;
}
```

## React hook for prices

```typescript hooks/useTokenPrice.ts theme={null}
import { useState, useEffect } from 'react';

const API_BASE = 'https://api.akka.finance';
const API_KEY = process.env.NEXT_PUBLIC_AKKA_API_KEY!;

interface TokenPrice {
  symbol: string;
  buyPriceUsd: number | null;
  sellPriceUsd: number | null;
}

export function useTokenPrice(chainId: number, tokenAddress: string) {
  const [price, setPrice] = useState<TokenPrice | null>(null);

  useEffect(() => {
    if (!tokenAddress) return;

    let cancelled = false;

    async function fetchPrice() {
      const res = await fetch(
        `${API_BASE}/${chainId}/tokens/${tokenAddress}`,
        { headers: { apikey: API_KEY } },
      );
      if (!res.ok || cancelled) return;
      const data = await res.json();
      setPrice({
        symbol: data.symbol,
        buyPriceUsd: data.buyPriceUsd,
        sellPriceUsd: data.sellPriceUsd,
      });
    }

    fetchPrice();
    const interval = setInterval(fetchPrice, 30_000);

    return () => { cancelled = true; clearInterval(interval); };
  }, [chainId, tokenAddress]);

  return price;
}
```

Usage:

```tsx theme={null}
const whypePrice = useTokenPrice(999, '0x5555555555555555555555555555555555555555');

return <span>WHYPE: ${whypePrice?.buyPriceUsd?.toFixed(2)}</span>;
```

## USD value helper

Convert a token amount in wei to its USD value:

```typescript theme={null}
import { formatUnits } from 'viem';

function toUsdValue(amountWei: string, decimals: number, priceUsd: number | null): string | null {
  if (!priceUsd) return null;
  const amount = Number(formatUnits(BigInt(amountWei), decimals));
  return (amount * priceUsd).toFixed(2);
}

// Example: 1 WHYPE (18 decimals) at $25.42
toUsdValue('1000000000000000000', 18, 25.42);
// → "25.42"
```

## Use cases

<CardGroup cols={2}>
  <Card title="Swap UI" icon="arrow-right-arrow-left">
    Show USD values next to token amounts so users know the dollar value of their swap.
  </Card>

  <Card title="Portfolio tracker" icon="wallet">
    Display wallet holdings in USD by multiplying token balances by their current prices.
  </Card>

  <Card title="Price alerts" icon="bell">
    Poll prices and trigger notifications when a token crosses a threshold.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track token price movements over time for dashboards and reporting.
  </Card>
</CardGroup>

<Info>
  Prices are derived from real DEX pool reserves across all indexed markets on HyperEVM. They reflect actual on-chain liquidity, not centralized exchange prices.
</Info>