npm package: @0xhustler/stablecoins
Description: A comprehensive library for obtaining stablecoin addresses across all major blockchain networks
Author: 0xHustler
Latest version: 1.0.0

# @0xhustler/stablecoins

A comprehensive library for obtaining stablecoin contract addresses across all major blockchain networks.

## Installation

```bash
npm install @0xhustler/stablecoins
```

```bash
yarn add @0xhustler/stablecoins
```

```bash
pnpm add @0xhustler/stablecoins
```

## Usage

### Basic Usage

```typescript
import { usdt, usdc, dai } from "@0xhustler/stablecoins";

// Get USDT address on Base
const usdtOnBase = usdt.addressOn("base");
// => "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2"

// Get USDC address on Arbitrum
const usdcOnArbitrum = usdc.addressOn("arbitrum");
// => "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"

// Get DAI address on Polygon
const daiOnPolygon = dai.addressOn("polygon");
// => "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063"
```

### Safe Address Retrieval

```typescript
import { usdt } from "@0xhustler/stablecoins";

// Returns undefined if not available
const address = usdt.addressOn("somechain");
if (address) {
  // Use address
}

// Throws error if not available
try {
  const address = usdt.addressOnOrThrow("somechain");
} catch (error) {
  console.error("USDT not available on this chain");
}
```

### Check Availability

```typescript
import { dai } from "@0xhustler/stablecoins";

// Check if available on a chain
if (dai.isAvailableOn("optimism")) {
  const address = dai.addressOn("optimism");
}

// Get all chains where a stablecoin is available
const chains = dai.availableChains();
// => ["ethereum", "base", "arbitrum", "optimism", "polygon", ...]
```

### Get Decimals

```typescript
import { usdt, dai } from "@0xhustler/stablecoins";

// USDT has 6 decimals on most chains
const usdtDecimals = usdt.decimalsOn("ethereum"); // => 6

// DAI has 18 decimals
const daiDecimals = dai.decimalsOn("ethereum"); // => 18
```

### Utility Functions

```typescript
import {
  getStablecoinBySymbol,
  getStablecoinsOnChain,
  allStablecoins
} from "@0xhustler/stablecoins";

// Get stablecoin by symbol
const usdc = getStablecoinBySymbol("USDC");
const address = usdc?.addressOn("base");

// Get all stablecoins available on a chain
const baseStablecoins = getStablecoinsOnChain("base");
baseStablecoins.forEach((coin) => {
  console.log(`${coin.symbol}: ${coin.addressOn("base")}`);
});

// Iterate over all stablecoins
Object.values(allStablecoins).forEach((coin) => {
  console.log(`${coin.name} (${coin.symbol})`);
});
```

## Supported Stablecoins

| Symbol | Name | Website |
|--------|------|---------|
| USDT | Tether USD | https://tether.to |
| USDC | USD Coin | https://www.circle.com/usdc |
| DAI | Dai Stablecoin | https://makerdao.com |
| FRAX | Frax | https://frax.finance |
| TUSD | TrueUSD | https://trueusd.com |
| USDP | Pax Dollar | https://paxos.com/usdp |
| LUSD | Liquity USD | https://www.liquity.org |
| GUSD | Gemini Dollar | https://www.gemini.com/dollar |
| sUSD | Synthetix USD | https://synthetix.io |
| crvUSD | Curve USD | https://curve.fi |
| PYUSD | PayPal USD | https://www.paypal.com/pyusd |
| BUSD | Binance USD | https://www.binance.com/busd |
| USDD | Decentralized USD | https://usdd.io |
| GHO | GHO | https://aave.com |
| FDUSD | First Digital USD | https://firstdigitallabs.com |
| MIM | Magic Internet Money | https://abracadabra.money |
| DOLA | DOLA | https://inverse.finance |
| EURS | Stasis Euro | https://stasis.net |
| EURT | Tether Euro | https://tether.to |
| EURC | Euro Coin | https://www.circle.com/eurc |
| USDe | Ethena USDe | https://ethena.fi |

## Supported Chains

### EVM Chains
- Ethereum
- Base
- Arbitrum
- Optimism
- Polygon
- Avalanche
- BSC (Binance Smart Chain)
- Fantom
- Gnosis
- Celo
- Moonbeam
- Linea
- Scroll
- zkSync
- Mantle
- Blast
- Mode

### Non-EVM Chains
- Solana
- TRON
- NEAR
- Aptos
- Sui

## TypeScript Support

This package includes full TypeScript support with type definitions.

```typescript
import type { Chain, Address, ChainAddresses } from "@0xhustler/stablecoins";

const chain: Chain = "ethereum";
const address: Address = "0x...";
```

## API Reference

### Stablecoin Class

| Method | Description |
|--------|-------------|
| `addressOn(chain)` | Get address for a chain (returns `undefined` if not available) |
| `addressOnOrThrow(chain)` | Get address for a chain (throws if not available) |
| `isAvailableOn(chain)` | Check if available on a chain |
| `availableChains()` | Get all chains where available |
| `decimalsOn(chain)` | Get decimals for a chain |
| `allAddresses()` | Get all addresses as a record |
| `chainId(chain)` | Get EVM chain ID |

### Properties

| Property | Description |
|----------|-------------|
| `name` | Full name of the stablecoin |
| `symbol` | Symbol (e.g., "USDT") |
| `website` | Official website URL |

## License

MIT