# CripChain API Documentation

REST + JSON API for pricing, quotes, swaps and transaction lookups on BNB Smart Chain (chain ID 56).

Base URL: `https://token.cripchain.com/api/v1`

## Conventions

- All responses are JSON: `{"success":true,"data":{…}}` or `{"success":false,"error":{"code":400,"message":"…"}}`.
- Amounts are human-readable decimal strings (e.g. `"1.5"`), never raw wei. Transaction objects carry a hex `value`.
- Rate limit: 60 requests per minute per IP (HTTP 429). CORS is open for GET and POST.
- **Non-custodial:** the API never receives private keys. Swap endpoints return unsigned transactions that the user's wallet signs.
- Errors: 400 invalid input · 404 not found · 429 rate limited · 502 upstream or RPC failure · 503 not configured, or no liquidity pool yet.

## Endpoints

### Status

#### `GET /health`

API and chain status.

Example:

```bash
curl "https://token.cripchain.com/api/v1/health"
```

Response `data`:

```json
{
    "status": "ok",
    "chainId": 56,
    "block": 43123456
}
```

### Token & Price

#### `GET /token`

On-chain token metadata (name, symbol, decimals, total supply).

Example:

```bash
curl "https://token.cripchain.com/api/v1/token"
```

Response `data`:

```json
{
    "address": "0x…",
    "name": "CripChain",
    "symbol": "CRIP",
    "decimals": 18,
    "totalSupply": "500000000",
    "chainId": 56,
    "explorer": "https://bscscan.com/token/0x…"
}
```

#### `GET /price`

Live CRIP price from the PancakeSwap V2 pool, in BNB and USD. Cached 10 s.

Example:

```bash
curl "https://token.cripchain.com/api/v1/price"
```

Response `data`:

```json
{
    "priceBnb": "0.0000021",
    "priceUsd": "0.00135",
    "bnbUsd": "640.2",
    "source": "PancakeSwap V2",
    "updatedAt": 1790000000
}
```

### Buy & Sell

#### `GET /quote/buy`

Quote for buying CRIP with BNB.

| Param | Type | Required | Description |
|---|---|---|---|
| `bnb` | number | yes | BNB to spend |
| `slippage` | number | no | Percent, 0–50. Default 1 |

Example:

```bash
curl "https://token.cripchain.com/api/v1/quote/buy?bnb=0.5"
```

Response `data`:

```json
{
    "spendBnb": "0.5",
    "expectedTokens": "238095.2",
    "minTokens": "235714.2",
    "slippagePct": "1"
}
```

#### `GET /quote/sell`

Quote for selling CRIP for BNB.

| Param | Type | Required | Description |
|---|---|---|---|
| `amount` | number | yes | CRIP to sell |
| `slippage` | number | no | Percent, 0–50. Default 1 |

Example:

```bash
curl "https://token.cripchain.com/api/v1/quote/sell?amount=1000"
```

Response `data`:

```json
{
    "sellTokens": "1000",
    "expectedBnb": "0.0021",
    "minBnb": "0.0020",
    "slippagePct": "1"
}
```

#### `POST /swap/buy`

Builds an unsigned buy transaction. Send `tx` with the user's wallet (`eth_sendTransaction`).

| Param | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Buyer wallet (receives CRIP) |
| `bnb` | number | yes | BNB to spend |
| `slippage` | number | no | Percent, 0–50. Default 1 |

Example:

```bash
curl -X POST https://token.cripchain.com/api/v1/swap/buy \
  -H "Content-Type: application/json" \
  -d '{"address":"0xYourWallet","bnb":"0.5"}'
```

Response `data`:

```json
{
    "tx": {
        "chainId": 56,
        "to": "0x10ED43C718714eb63d5aA57B78B54704E256024E",
        "value": "0x6f05b59d3b20000",
        "data": "0xb6f9de95…"
    },
    "expectedTokens": "238095.2",
    "minTokens": "235714.2"
}
```

#### `POST /swap/sell`

Builds an unsigned sell transaction. If the router allowance is too low, `approveTx` is returned and must be sent and confirmed first.

| Param | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Seller wallet |
| `amount` | number | yes | CRIP to sell |
| `slippage` | number | no | Percent, 0–50. Default 1 |

Example:

```bash
curl -X POST https://token.cripchain.com/api/v1/swap/sell \
  -H "Content-Type: application/json" \
  -d '{"address":"0xYourWallet","amount":"1000"}'
```

Response `data`:

```json
{
    "approveTx": {
        "chainId": 56,
        "to": "0xTOKEN",
        "value": "0x0",
        "data": "0x095ea7b3…"
    },
    "tx": {
        "chainId": 56,
        "to": "0x10ED43C718714eb63d5aA57B78B54704E256024E",
        "value": "0x0",
        "data": "0x791ac947…"
    },
    "expectedBnb": "0.0021",
    "minBnb": "0.0020"
}
```

### Wallet & Transactions

#### `GET /balance/{address}`

CRIP and BNB balance of a wallet.

| Param | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Wallet address (in the path) |

Example:

```bash
curl "https://token.cripchain.com/api/v1/balance/0xYourWallet"
```

Response `data`:

```json
{
    "address": "0x…",
    "token": "15000.5",
    "bnb": "0.42"
}
```

#### `GET /tx/{hash}`

Transaction status: `pending`, `success` or `failed`, with confirmations.

| Param | Type | Required | Description |
|---|---|---|---|
| `hash` | string | yes | Transaction hash (in the path) |

Example:

```bash
curl "https://token.cripchain.com/api/v1/tx/0xTRANSACTION_HASH"
```

Response `data`:

```json
{
    "hash": "0x…",
    "status": "success",
    "from": "0x…",
    "to": "0x…",
    "valueBnb": "0.5",
    "blockNumber": 43123400,
    "confirmations": 12,
    "gasUsed": 152340,
    "explorer": "https://bscscan.com/tx/0x…"
}
```

#### `GET /transfers/{address}`

CRIP transfer history for a wallet. Needs `CRIP_EXPLORER_KEY` on the server.

| Param | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Wallet address (in the path) |
| `page` | int | no | Default 1 |
| `limit` | int | no | 1–100, default 20 |

Example:

```bash
curl "https://token.cripchain.com/api/v1/transfers/0xYourWallet"
```

Response `data`:

```json
{
    "address": "0x…",
    "page": 1,
    "items": [
        {
            "hash": "0x…",
            "from": "0x…",
            "to": "0x…",
            "amount": "1000",
            "direction": "in",
            "block": 43123400,
            "timestamp": 1790000000
        }
    ]
}
```

### Market data

#### `GET /market/tickers`

Live 24h stats for major pairs (BTC, ETH, BNB, SOL, XRP, ADA, DOGE, TRX, AVAX, LINK vs USDT). Source: Binance public feed, cached 10 s.

Example:

```bash
curl "https://token.cripchain.com/api/v1/market/tickers"
```

Response `data`:

```json
[
    {
        "symbol": "BNBUSDT",
        "base": "BNB",
        "price": "640.20",
        "changePct": "1.85",
        "high": "652.1",
        "low": "628.0",
        "volumeUsd": "182345678.12"
    }
]
```

#### `GET /market/klines`

Candlestick (OHLCV) data, last 200 candles.

| Param | Type | Required | Description |
|---|---|---|---|
| `symbol` | string | no | e.g. BNBUSDT (default) |
| `interval` | string | no | 5m, 15m, 1h (default), 4h, 1d |

Example:

```bash
curl "https://token.cripchain.com/api/v1/market/klines"
```

Response `data`:

```json
[
    {
        "time": 1790000000,
        "open": 638.1,
        "high": 641,
        "low": 637.5,
        "close": 640.2,
        "volume": 1523.4
    }
]
```

### Site content

#### `GET /site`

Public site content (tokenomics, roadmap, FAQ, buy links) managed in the admin panel.

Example:

```bash
curl "https://token.cripchain.com/api/v1/site"
```

Response `data`:

```json
{
    "name": "CripChain",
    "symbol": "CRIP",
    "total_supply": "500000000"
}
```