bou-wallet

# BOU Wallet

Use direct HTTP requests with `curl`. Prefer this skill when the task is to operate this backend through an existing agent bearer key instead of building a separate SDK or CLI first.

## First-time setup after install

If the user has installed this skill but does not have an agent API key yet, walk them through this setup first:

1. Open `https://app.bankofuniverse.org/`
2. Sign in, then create an agent in the app
3. Generate the agent API key, then copy it and use it as `AGENT_KEY` in requests

If the user has not completed these steps yet, do not pretend the skill can run successfully. First help them obtain a valid `ak_...` key.

## Required inputs

Collect these values before making any request:

- `BASE_URL`: use `https://api.bankofuniverse.org/` unless the user explicitly gives a different backend
- `AGENT_KEY`: bearer token in `ak_...` format

Treat the agent key as secret. Do not print, commit, or store it in repo files.

## Common request pattern

Use the same bearer auth for all three capability groups.

```sh
curl -sS "$BASE_URL/..." \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Accept: application/json"
```

For JSON request bodies, also add:

```sh
-H "Content-Type: application/json"
```

Most responses use the shared wrapper:

```json
{
  "code": 0,
  "message": "",
  "data": {}
}
```

## Capability 1: x402 pay-and-call

Use `POST /agent/pay-and-call` when the agent needs to access an x402-protected upstream URL through this backend. Call this backend endpoint, not the merchant directly.

Body shape:

```json
{
  "url": "https://merchant.example.com/path",
  "method": "GET",
  "headers": {
    "X-Custom-Header": "value"
  },
  "body": {
    "query": "ETH price"
  }
}
```

Rules:

- Send a full upstream `http://` or `https://` URL in `url`
- Use the upstream HTTP verb in `method`
- Pass merchant headers as a JSON object when needed
- Pass `body` only when the upstream endpoint expects one
- The backend enforces agent status and USDC payment limits before paying
- The backend rejects requests when the required payment is `>= 0.1` USDC

Example:

```sh
curl -sS -X POST "$BASE_URL/agent/pay-and-call" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/search",
    "method": "POST",
    "body": {
      "query": "BTC"
    }
  }'
```

### x402 test cases

Use these upstream URLs to quickly test the `pay-and-call` flow.

#### Test case 1: random number

Upstream endpoint:

- `GET /cos/crypto/chainlink/random`

Expected response body:

```json
{
  "number": 42
}
```

Example:

```sh
curl -sS -X POST "https://api.bankofuniverse.org/agent/pay-and-call" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://skills.bankofuniverse.org/cos/crypto/chainlink/random",
    "method": "GET"
  }'
```

#### Test case 2: crypto price

Upstream endpoint:

- `GET /cos/crypto/price/:symbol`

Supported symbols:

- `ETH`
- `BTC`
- `USDC`
- `USDT`
- `TRX`
- `BNB`

Expected response body:

```json
{
  "symbol": "BTC",
  "supportedSymbols": ["ETH", "BTC", "USDC", "USDT", "TRX", "BNB"],
  "price": 84000.12,
  "timestamp": 1710000000000
}
```

Example:

```sh
curl -sS -X POST "https://api.bankofuniverse.org/agent/pay-and-call" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://skills.bankofuniverse.org/cos/crypto/price/BTC",
    "method": "GET"
  }'
```

## Capability 2: current agent info

Use `GET /agent/me` to inspect the current agent resolved by the bearer key.

This endpoint returns the resolved agent, matched API key metadata, cumulative spent USDC, and a best-effort Base USDC balance lookup.

Example:

```sh
curl -sS "$BASE_URL/agent/me" \
  -H "Authorization: Bearer $AGENT_KEY"
```

## Capability 3: Hyperliquid operations

Use the `/hyperliquid` endpoints when the agent needs to inspect or trade through the backend's Hyperliquid integration. All requests use the same bearer auth pattern.

### Read endpoints

- `GET /hyperliquid/status`
  Purpose: verify the current agent is authorized to use Hyperliquid for the resolved account.
  Key return fields: `address` is the resolved Hyperliquid account address. In agent mode, the response may also include signer-related identity information returned by the backend.
  Use it when: you want to confirm the bearer key is valid and Hyperliquid access is ready before reading balances or sending orders.
- `GET /hyperliquid/balances`
  Purpose: fetch the latest account balance snapshot from Hyperliquid.
  Key return fields: `data` contains the balance payload returned by Hyperliquid for the resolved account, including available funds and account balance details.
  Use it when: you need to check available funds before trading, transferring, or withdrawing.
- `GET /hyperliquid/open-orders?coin=BTC`
  Purpose: list current open orders, optionally filtered by one symbol.
  Key return fields: each item is normalized to include readable `coin`, `side`, and `marketType`; the rest of the item is the underlying open-order data.
  Use it when: you want to inspect working orders before canceling or placing another order.
- `GET /hyperliquid/markets?marketType=perp`
  Purpose: list supported spot or perp markets.
  Key return fields: spot markets include fields such as `coin`, `pairId`, `base`, `quote`, `szDecimals`, `weiDecimals`, and `marketType`; perp markets include fields such as `coin`, `base`, `quote`, `dexName`, `maxLeverage`, `szDecimals`, `onlyIsolated`, `marginMode`, and `marketType`.
  Use it when: you need to discover valid symbols, decimals, supported dex markets, or leverage-related metadata before trading.
- `GET /hyperliquid/active-asset-data?coin=BTC`
  Purpose: inspect the current account trading state for one perp coin.
  Key return fields: `coin`, `leverage`, `isCross`, `leverageType`, `maxTradeSzs`, `availableToTrade`, and `markPx`.
  `maxTradeSzs` and `availableToTrade` are two-element arrays: index `0` is the `BUY` value and index `1` is the `SELL` value.
  Use it when: you need the current leverage mode, tradeable size, or mark price for a perp coin before placing or sizing an order.
- `GET /hyperliquid/funding?coin=BTC`
  Purpose: fetch current and next funding information for one perp market.
  Key return fields: `coin`, `fundingRate`, `nextFundingRate`, `nextFundingTimestamp`, `markPrice`, and `indexPrice`.
  Use it when: you want to evaluate funding cost, expected next funding, or compare mark price with oracle/index price.
- `GET /hyperliquid/orderbook?coin=BTC`
  Purpose: fetch the live L2 order book for one market.
  Key return fields: `data` is the raw Hyperliquid order book snapshot, including bid and ask levels plus the snapshot time.
  Use it when: you need market depth, best bid/ask context, or raw book levels for quoting and execution logic.
- `GET /hyperliquid/positions`
  Purpose: list current perp positions across available dex contexts for the account.
  Key return fields: each position includes `dexName`, `marketType`, `coin`, `szi`, `leverage`, `isCross`, `leverageType`, `entryPx`, `positionValue`, `unrealizedPnl`, `returnOnEquity`, `liquidationPx`, `marginUsed`, `maxLeverage`, and `cumFunding`.
  Use it when: you want a full view of current exposure, PnL, liquidation risk, and leverage usage.
- `GET /hyperliquid/fills?coin=BTC&since=1710000000000&limit=100`
  Purpose: list historical fills for the account, optionally filtered by symbol, start time, and result count.
  Key return fields: each fill is normalized to include readable `coin`, `side`, and `marketType`; the rest of the fill fields come from Hyperliquid's fill history.
  Use it when: you want recent execution history for trade reconciliation, reporting, or strategy logic.
- `GET /hyperliquid/ticker?coin=BTC&marketType=perp`
  Purpose: fetch a compact ticker-style market snapshot for one symbol.
  Key return fields: `coin`, `marketType`, `last`, `bid`, `ask`, `open`, `close`, `change`, `percentage`, `volume`, `quoteVolume`, and `timestamp`.
  Use it when: you need a lightweight summary of current price, spread, daily move, and volume without reading the full order book.

Query rules:

- `marketType`: `perp` or `spot`
- `coin`: short asset symbol such as `BTC` or `ETH`
- `limit` for fills: `1` to `500`
- `nSigFigs` for orderbook: `2`, `3`, `4`, or `5`
- `mantissa` for orderbook: `2` or `5`

### Write endpoints

- `POST /hyperliquid/order`
- `POST /hyperliquid/cancel`
- `POST /hyperliquid/cancel-all`
- `POST /hyperliquid/set-leverage`
- `POST /hyperliquid/transfer`
- `POST /hyperliquid/withdraw`

#### Place order

Request body:

```json
{
  "coin": "BTC",
  "marketType": "perp",
  "orderType": "limit",
  "side": "BUY",
  "size": "0.001",
  "price": "50000",
  "reduceOnly": false,
  "timeInForce": "Gtc"
}
```

Field rules:

- `orderType`: `market`, `limit`, `stop_limit`, `stop_market`, or `twap`
- `side`: `BUY` or `SELL`
- `size`: numeric string
- `price`: optional in the DTO, but required for limit-style orders such as `limit` and `stop_limit`
- `triggerPrice`: optional in the DTO, but use it for stop orders such as `stop_limit` and `stop_market`
- `tpPrice` and `slPrice`: optional take-profit and stop-loss values
- `timeInForce`: `Gtc`, `Ioc`, or `Alo`
- `durationMinutes`: optional in the DTO, min `5`, max `1440`; use it for TWAP-style flows when required by the backend logic
- `randomizeSlices`: optional boolean for TWAP-style flows

Example:

```sh
curl -sS -X POST "$BASE_URL/hyperliquid/order" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coin": "BTC",
    "marketType": "perp",
    "orderType": "limit",
    "side": "BUY",
    "size": "0.001",
    "price": "50000"
  }'
```

#### Cancel selected orders

Request body:

```json
{
  "orders": [
    {
      "coin": "BTC",
      "orderId": 123456
    }
  ]
}
```

Field rules:

- `orders`: required array with at most `100` items
- `coin`: required string for each item
- `orderId`: required integer for each item, minimum `0`

#### Cancel all orders

Request body:

```json
{
  "coin": "BTC"
}
```

Omit `coin` to cancel all open orders across supported assets.

#### Set leverage

Request body:

```json
{
  "coin": "BTC",
  "leverage": 5,
  "isCross": true
}
```

#### Transfer asset

Request body:

```json
{
  "amount": "10",
  "dex": "",
  "fromPerp": true
}
```

Field rules:

- `amount`: required numeric string
- `dex`: optional dex name string; omit it to use the primary dex.
- `fromPerp`: optional boolean, `true` means transfer from perp side

#### Withdraw asset

Use this endpoint to withdraw Perps USDC to the Arbitrum network.

Request body:

```json
{
  "destination": "0x1234567890abcdef1234567890abcdef12345678",
  "amount": "10"
}
```

Field rules:

- `destination`: required EVM address
- `amount`: required numeric string

## Execution checklist

Before running requests:

- Verify `BASE_URL` is correct
- Verify the token looks like `ak_...`
- Verify JSON is valid
- Verify Hyperliquid enum values match the accepted casing exactly
- Prefer the two built-in x402 test cases above when validating a new agent key
- Use `-i` when you need status codes or headers for debugging

If a request fails, inspect the wrapped JSON `message` plus the HTTP status first.