skillpp 0.1.0

package/skills/binance-web3/binance-agentic-wallet/references/prediction.md

@@ -0,0 +1,489 @@
+# Prediction Markets
+
+Browse prediction markets, query the user's positions and orders, and trade outcome tokens.
+
+A prediction **market** asks a yes/no (or multi-outcome) question that will resolve at some point in the future. Each outcome is represented by an ERC-1155 **outcome token**. Buying an outcome token is betting on that outcome; if the market resolves in your favor, the token can be redeemed for payout.
+
+Commands are grouped into three categories: **market/category queries**, **position/order queries**, and **trade commands** (`quote`, `place-order`, `cancel`, `redeem`).
+
+---
+
+## `prediction category list`
+
+List available prediction market categories (e.g. crypto, sports, politics).
+
+### Syntax
+
+```bash
+baw prediction category list --json
+```
+
+### Example
+
+```bash
+baw prediction category list --json
+```
+
+---
+
+## `prediction market list`
+
+List prediction markets, optionally filtered by category and sorted.
+
+### Syntax
+
+```bash
+baw prediction market list [--l1Category <category>] [--l2Category <category>] [--sortBy <sort>] [--orderBy <order>] [--offset <offset>] [--limit <limit>] --json
+```
+
+### Parameters
+
+| Parameter      | Required | Default | Description                                                                    |
+|----------------|----------|---------|--------------------------------------------------------------------------------|
+| `--l1Category` | No       | —       | L1 category filter (e.g. `crypto`, `sports`). From `prediction category list`. |
+| `--l2Category` | No       | —       | L2 subcategory filter                                                          |
+| `--sortBy`     | No       | —       | `RECOMMENDED`, `VOLUME`, `PARTICIPANTS`, `CREATED_TIME`, `END_DATE`            |
+| `--orderBy`    | No       | `DESC`  | `ASC` or `DESC`                                                                |
+| `--offset`     | No       | `0`     | Pagination offset                                                              |
+| `--limit`      | No       | `20`    | Page size, max 100                                                             |
+
+### Example
+
+```bash
+baw prediction market list --json
+baw prediction market list --l1Category crypto --limit 5 --json
+baw prediction market list --sortBy VOLUME --orderBy DESC --json
+```
+
+---
+
+## `prediction market detail`
+
+Get the full detail of a single prediction market by its topic ID.
+
+### Syntax
+
+```bash
+baw prediction market detail --marketTopicId <id> --json
+```
+
+### Parameters
+
+| Parameter         | Required | Default | Description     |
+|-------------------|----------|---------|-----------------|
+| `--marketTopicId` | Yes      | —       | Market topic ID |
+
+### Example
+
+```bash
+baw prediction market detail --marketTopicId 123456 --json
+```
+
+---
+
+## `prediction market search`
+
+Search prediction markets by keyword.
+
+### Syntax
+
+```bash
+baw prediction market search --query <query> [--limit <limit>] --json
+```
+
+### Parameters
+
+| Parameter | Required | Default | Description                   |
+|-----------|----------|---------|-------------------------------|
+| `--query` | Yes      | —       | Search keyword, max 200 chars |
+| `--limit` | No       | `10`    | Max results, max 50           |
+
+### Example
+
+```bash
+baw prediction market search --query "Bitcoin" --json
+baw prediction market search --query "FIFA World Cup" --limit 5 --json
+```
+
+---
+
+## `prediction market order-book`
+
+Get the order book for a specific outcome token.
+
+### Syntax
+
+```bash
+baw prediction market order-book --marketId <id> --tokenId <tokenId> --json
+```
+
+### Parameters
+
+| Parameter    | Required | Default | Description      |
+|--------------|----------|---------|------------------|
+| `--marketId` | Yes      | —       | Market ID        |
+| `--tokenId`  | Yes      | —       | Outcome token ID |
+
+### Example
+
+```bash
+baw prediction market order-book --marketId 789 --tokenId 123456789 --json
+```
+
+---
+
+## `prediction market last-trade-price`
+
+Get the last trade price for a market.
+
+This is a **historical fill price**, not a live market quote — it can be stale if there have been no recent trades, and it does not reflect the current best bid/ask.
+
+### Syntax
+
+```bash
+baw prediction market last-trade-price --marketId <id> --json
+```
+
+### Parameters
+
+| Parameter    | Required | Default | Description |
+|--------------|----------|---------|-------------|
+| `--marketId` | Yes      | —       | Market ID   |
+
+### Example
+
+```bash
+baw prediction market last-trade-price --marketId 789 --json
+```
+
+---
+
+## `prediction position list`
+
+List the user's active and past prediction positions with PnL summary.
+
+### Syntax
+
+```bash
+baw prediction position list [--tab <tab>] [--offset <offset>] [--limit <limit>] --json
+```
+
+### Parameters
+
+| Parameter  | Required | Default   | Description                                 |
+|------------|----------|-----------|---------------------------------------------|
+| `--tab`    | No       | `ONGOING` | Filter: `ONGOING`, `ENDED`, `PENDING_CLAIM` |
+| `--offset` | No       | `0`       | Pagination offset                           |
+| `--limit`  | No       | `20`      | Page size, max 100                          |
+
+`PENDING_CLAIM` surfaces winning positions that have not yet been redeemed — use [`prediction trade redeem`](#prediction-trade-redeem) to claim them.
+
+### Example
+
+```bash
+baw prediction position list --json
+baw prediction position list --tab PENDING_CLAIM --json
+```
+
+---
+
+## `prediction position token`
+
+Look up a single position by its ERC-1155 outcome token ID.
+
+### Syntax
+
+```bash
+baw prediction position token --tokenId <tokenId> --json
+```
+
+### Parameters
+
+| Parameter   | Required | Default | Description               |
+|-------------|----------|---------|---------------------------|
+| `--tokenId` | Yes      | —       | ERC-1155 outcome token ID |
+
+### Example
+
+```bash
+baw prediction position token --tokenId 123456789 --json
+```
+
+---
+
+## `prediction position settled-history`
+
+List the user's settled (finalized) prediction positions, with optional win/lose filtering.
+
+### Syntax
+
+```bash
+baw prediction position settled-history [--l1Category <category>] [--filter <filter>] [--offset <offset>] [--limit <limit>] --json
+```
+
+### Parameters
+
+| Parameter      | Required | Default | Description                                  |
+|----------------|----------|---------|----------------------------------------------|
+| `--l1Category` | No       | —       | L1 category filter (e.g. `crypto`, `sports`) |
+| `--filter`     | No       | `all`   | `all`, `win`, `lose`                         |
+| `--offset`     | No       | `0`     | Pagination offset                            |
+| `--limit`      | No       | `20`    | Page size, max 100                           |
+
+### Example
+
+```bash
+baw prediction position settled-history --json
+baw prediction position settled-history --filter win --json
+baw prediction position settled-history --filter lose --json
+```
+
+---
+
+## `prediction position pnl`
+
+Query detailed PnL records for the user's prediction positions.
+
+### Syntax
+
+```bash
+baw prediction position pnl [--tokenId <tokenId>] [--l1Category <category>] [--offset <offset>] [--limit <limit>] --json
+```
+
+### Parameters
+
+| Parameter      | Required | Default | Description                                      |
+|----------------|----------|---------|--------------------------------------------------|
+| `--tokenId`    | No       | —       | Filter by a specific token ID                    |
+| `--l1Category` | No       | —       | L1 category filter: `crypto`, `sports`, `all`    |
+| `--offset`     | No       | `0`     | Pagination offset                                |
+| `--limit`      | No       | `20`    | Page size, max 100                               |
+
+### Example
+
+```bash
+baw prediction position pnl --json
+baw prediction position pnl --l1Category crypto --json
+baw prediction position pnl --tokenId abc123 --json
+```
+
+---
+
+## `prediction position portfolio`
+
+Get a portfolio-level summary of the user's active prediction positions, including unrealized PnL.
+
+### Syntax
+
+```bash
+baw prediction position portfolio --json
+```
+
+### Example
+
+```bash
+baw prediction position portfolio --json
+```
+
+---
+
+## `prediction order history`
+
+List the user's historical prediction orders across all statuses.
+
+### Syntax
+
+```bash
+baw prediction order history [--status <status>] [--l1Category <category>] [--orderType <type>] [--offset <offset>] [--limit <limit>] --json
+```
+
+### Parameters
+
+| Parameter      | Required | Default | Description                                                                            |
+|----------------|----------|---------|----------------------------------------------------------------------------------------|
+| `--status`     | No       | —       | `PENDING`, `SUBMITTED`, `FILLED`, `PARTIALLY_FILLED`, `CANCELLED`, `FAILED`, `EXPIRED` |
+| `--l1Category` | No       | —       | L1 category filter                                                                     |
+| `--orderType`  | No       | —       | `MARKET` or `LIMIT`                                                                    |
+| `--offset`     | No       | `0`     | Pagination offset                                                                      |
+| `--limit`      | No       | `20`    | Page size, max 100                                                                     |
+
+### Example
+
+```bash
+baw prediction order history --json
+baw prediction order history --status FILLED --limit 10 --json
+baw prediction order history --orderType LIMIT --json
+```
+
+### Order Status
+
+| Status             | Description                                   |
+|--------------------|-----------------------------------------------|
+| `PENDING`          | Order created but not yet submitted to vendor |
+| `SUBMITTED`        | Order submitted to vendor, awaiting execution |
+| `FILLED`           | Order fully filled                            |
+| `PARTIALLY_FILLED` | Order partially filled                        |
+| `CANCELLED`        | Order cancelled by user or system             |
+| `FAILED`           | Order failed to execute                       |
+| `EXPIRED`          | Expired due to market ends                    |
+
+---
+
+## Trading Flow
+
+Prediction trading is a **two-step** flow:
+
+1. **Quote** — call [`prediction trade quote`](#prediction-trade-quote) to get a `quoteId` and the expected cost / payout.
+2. **Confirm with the user** — show them the quote (price, amount, expected payout) and require an explicit "yes" before proceeding. Remind them to DYOR.
+3. **Place** — call [`prediction trade place-order`](#prediction-trade-place-order) with the `quoteId` from step 1.
+
+Quotes expire; if placement fails because the quote is stale, fetch a new quote and try again.
+
+---
+
+## `prediction trade quote`
+
+Get a trade quote for an outcome token. Returns a `quoteId` that must be passed to `place-order` within the quote's validity window.
+
+### Syntax
+
+```bash
+baw prediction trade quote --binanceChainId <binanceChainId> --tokenId <tokenId> --marketTopicId <marketTopicId> --side <side> --amount <amount> --orderType <type> [--slippageBps <bps>] [--priceLimit <price>] --json
+```
+
+### Parameters
+
+| Parameter          | Required       | Default        | Description                                                                                           |
+|--------------------|----------------|----------------|-------------------------------------------------------------------------------------------------------|
+| `--binanceChainId` | Yes            | —              | Binance chain ID                                                                                      |
+| `--tokenId`        | Yes            | —              | ERC-1155 outcome token ID                                                                             |
+| `--side`           | Yes            | —              | `BUY` or `SELL`                                                                                       |
+| `--amount`         | Yes            | —              | Trade amount, human-readable. Unit depends on `--side`: USDT for `BUY`, shares for `SELL`.            |
+| `--marketTopicId`  | Yes            | —              | Market topic ID. If `--slippageBps` is omitted, the market's default slippage is fetched via this ID. |
+| `--orderType`      | Yes            | —              | `MARKET` or `LIMIT`                                                                                   |
+| `--slippageBps`    | No             | market default | Slippage in basis points (e.g. `1200` = 12%)                                                          |
+| `--priceLimit`     | For LIMIT only | —              | Limit price in USDT — required when `--orderType LIMIT`                                               |
+
+### Example
+
+```bash
+# Market BUY quote
+baw prediction trade quote --binanceChainId 56 --tokenId abc123 --marketTopicId 123 --side BUY --amount 1 --orderType MARKET --json
+{
+  "success": true,
+  "data": {
+    "quoteId": "1234567890",
+    "tokenId": "abc123",
+    "side": "BUY",
+    "amountIn": "1",
+    "amountOut": "1.021983640081799586",
+    "averagePrice": 0.978,
+    "lastPrice": 0.978,
+    "priceImpact": 0,
+    "feeAmount": "0.000460018149807002",
+    "minReceive": "0.919831382438179829",
+    "expireAt": "2026-05-21T17:30:29+08:00",
+    "chainId": "56",
+    "orderType": "MARKET",
+    "slippageBps": 1000,
+    "marketTitle": "No change"
+  }
+}
+```
+
+Note on units — `amountIn`, `amountOut`, `feeAmount`, and `minReceive` swap units with `--side`:
+
+| Field        | `BUY`                         | `SELL`                      |
+|--------------|-------------------------------|-----------------------------|
+| `amountIn`   | USDT spent                    | shares sold                 |
+| `amountOut`  | shares received               | USDT received               |
+| `feeAmount`  | shares (provider service fee) | USDT (provider service fee) |
+| `minReceive` | shares (worst-case fill)      | USDT (worst-case proceeds)  |
+
+---
+
+## `prediction trade place-order`
+
+Place an order using a `quoteId` obtained from `prediction trade quote`. This is a **state-changing** command — always confirm with the user first.
+
+### Syntax
+
+```bash
+baw prediction trade place-order --quoteId <quoteId> --slippageBps <bps> [--orderType <type>] [--priceLimit <price>] --json
+```
+
+### Parameters
+
+| Parameter       | Required       | Default  | Description                                                      |
+|-----------------|----------------|----------|------------------------------------------------------------------|
+| `--quoteId`     | Yes            | —        | Quote ID returned from `prediction trade quote`                  |
+| `--slippageBps` | Yes            | —        | Slippage in basis points (from quote response slippageBps field) |
+| `--orderType`   | No             | `MARKET` | `MARKET` or `LIMIT`                                              |
+| `--priceLimit`  | For LIMIT only | —        | Limit price in USDT — required for LIMIT orders                  |
+
+### Example
+
+```bash
+baw prediction trade place-order --quoteId quote_abc123 --slippageBps 1000 --json
+
+baw prediction trade place-order --quoteId quote_abc123 --slippageBps 1000 --orderType LIMIT --priceLimit 0.6 --json
+```
+
+### Important: placing an order does not mean it is filled
+
+A successful response means the order has been **submitted**. For `MARKET` orders, fills usually happen quickly; `LIMIT` orders rest on the book until the trigger price is reached. After placement, tell the user:
+
+1. The order has been submitted.
+2. They can check its status with [`prediction order history`](#prediction-order-history).
+3. They should verify execution before assuming the trade is complete.
+
+---
+
+## `prediction trade cancel`
+
+Cancel one or more open prediction orders.
+
+### Syntax
+
+```bash
+baw prediction trade cancel --orderIds <ids> --json
+```
+
+### Parameters
+
+| Parameter    | Required | Default | Description                       |
+|--------------|----------|---------|-----------------------------------|
+| `--orderIds` | Yes      | —       | Comma-separated list of order IDs |
+
+### Example
+
+```bash
+baw prediction trade cancel --orderIds order_123,order_456 --json
+```
+
+---
+
+## `prediction trade redeem`
+
+Redeem (claim) the payout from winning prediction positions once their markets have resolved. Use [`prediction position list`](#prediction-position-list) with `--tab PENDING_CLAIM` to find token IDs that are redeemable.
+
+### Syntax
+
+```bash
+baw prediction trade redeem --tokenIds <ids> [--binanceChainId <binanceChainId>] --json
+```
+
+### Parameters
+
+| Parameter          | Required | Default | Description                               |
+|--------------------|----------|---------|-------------------------------------------|
+| `--tokenIds`       | Yes      | —       | Comma-separated list of winning token IDs |
+| `--binanceChainId` | No       | —       | Binance chain ID filter                   |
+
+### Example
+
+```bash
+baw prediction trade redeem --tokenIds token_123,token_456 --json
+
+baw prediction trade redeem --tokenIds token_123 --binanceChainId 56 --json
+```

package/skills/binance-web3/binance-agentic-wallet/references/preflight.md

@@ -0,0 +1,66 @@
+# Preflight Checks
+
+At the start of each conversation, run the following checks in order.
+
+---
+
+## 1. Skill Version Check
+
+Check whether a newer version of this skill is available. `currentSkillVersion` is the value of `metadata.version` in this skill's SKILL.md frontmatter.
+
+### Syntax
+
+```bash
+baw skill-check --skill-name binance-agentic-wallet --current-version ${currentSkillVersion} --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "needUpdateSkill": true,
+    "latestSkillVersion": "x.y.z"
+  }
+}
+```
+
+- **`needUpdateSkill` = true** → prompt the user: "A new version of the Binance Agentic Wallet skill is available (current: {currentSkillVersion}, latest: {latestSkillVersion}). Would you like to update now?" If the user confirms, install the latest version from https://github.com/binance/binance-skills-hub, then **re-read this file** before continuing to step 2 (the updated skill may require a different CLI version).
+- **`needUpdateSkill` = false**, or the request fails → proceed silently.
+
+---
+
+## 2. CLI Version Check
+
+Verify that the `baw` CLI meets the required version. The `requiredCliVersion` is the value of `metadata.requiredCliVersion` in this skill's SKILL.md frontmatter.
+
+### Syntax
+
+```bash
+baw cli-check --required-version ${requiredCliVersion} --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "currentCliVersion": "x.y.z",
+    "needUpdateCli": false
+  }
+}
+```
+
+- **`baw` not found** → install the required version.
+- **`needUpdateCli` = true** → upgrade to the required version.
+- **`needUpdateCli` = false** → no action needed.
+
+### Install / Upgrade the CLI
+
+The `baw` CLI is distributed as the npm package `@binance/agentic-wallet`. Use the following command to install or upgrade the required CLI version:
+
+```bash
+npm install -g @binance/agentic-wallet@${requiredCliVersion}
+```

package/skills/binance-web3/binance-agentic-wallet/references/security.md

@@ -0,0 +1,47 @@
+# Security Reference
+
+Security pre-check procedures for swap operations.
+
+---
+
+## §1 Swap Security Pre-Check
+
+> **Applies to**: `market-order swap` in [market-order.md](market-order.md), `limit-order buy` / `limit-order sell` in [limit-order.md](limit-order.md)
+
+Before constructing any swap command, perform the following steps:
+
+### Step 1: Identify the target token
+
+- For `market-order swap` and `limit-order buy`: the target is `--toToken`
+- For `limit-order sell`: the target is `--toToken` (already restricted to BNB/USDT/USDC, so skip to Step 4)
+- If the target is a known trusted asset from the **Common Token Addresses** table in SKILL.md → skip to Step 4
+
+### Step 2: Call the Token Audit
+
+Use the `query-token-audit` skill to audit the target token. If the user has not installed this skill, recommend they install it from https://github.com/binance/binance-skills-hub
+
+Call the Token Security Audit API with the target token's `contractAddress` and `binanceChainId`. See the `query-token-audit` skill documentation for the full API specification, request format, and response fields.
+
+**Result validity**: Only proceed to Step 3 when **both** `hasResult: true` AND `isSupported: true`. Otherwise, skip to Unavailable Handling below.
+
+### Step 3: Interpret audit results and present to user
+
+Parse the response and present a security summary to the user. Refer to the `query-token-audit` skill documentation for field meanings, risk level definitions, and tax thresholds.
+
+- Present all hit risk items (`isHit: true`) with their descriptions
+- Highlight tax rates if abnormal (>5% warning, >10% high risk)
+- Let the user decide whether to proceed
+
+### Step 4: Continue with swap flow
+
+If the user decides to proceed, continue with the standard swap flow in the relevant reference file (confirm slippage → build command → execute).
+
+### Unavailable Handling
+
+| Scenario                                       | Action                                                                                                                                                                                                                                                                                                         |
+|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Audit API call fails (network / timeout / 5xx) | Warn: "Token security audit is temporarily unavailable." Require explicit user acknowledgment before proceeding.                                                                                                                                                                                               |
+| `hasResult: false` OR `isSupported: false`     | Reply: "Security audit data is not available for this token on this chain." Do **NOT** display `riskLevel`, `riskLevelEnum`, or `riskItems` — data is unreliable when either field is false. Suggest the user verify the contract address and chain, or try again later. Require explicit user acknowledgment. |
+| `query-token-audit` skill not installed        | Inform the user: "The token audit skill is not installed. Install it for pre-trade security checks from https://github.com/binance/binance-skills-hub." Require explicit user acknowledgment before proceeding without audit.                                                                                  |
+
+Never silently skip. The user must always be informed before proceeding.

package/skills/binance-web3/binance-agentic-wallet/references/send.md

@@ -0,0 +1,53 @@
+# Send Tokens
+
+Transfer tokens to a recipient address.
+
+## `wallet send`
+
+### Syntax
+
+```bash
+baw wallet send --amount <amount> --recipient <recipient> --binanceChainId <binanceChainId> --tokenAddress <tokenAddress> [--gasLevel <gasLevel>] --json
+```
+
+### Parameters
+
+| Parameter          | Required | Default | Description                                                                                   |
+|--------------------|----------|---------|-----------------------------------------------------------------------------------------------|
+| `--amount`         | Yes      | —       | Amount in human-readable units (e.g., `1.5`)                                                  |
+| `--recipient`      | Yes      | —       | Recipient wallet address (must be in the [address book](#address-book)), ENS is not supported |
+| `--binanceChainId` | Yes      | —       | Binance chain ID: `56` (BSC), `CT_501` (Solana). For a full list, see `wallet chains`         |
+| `--tokenAddress`   | Yes      | —       | Token contract address                                                                        |
+| `--gasLevel`       | No       | `HIGH`  | Gas level: "LOW", "MEDIUM", or "HIGH"                                                         |
+
+### Example
+
+```bash
+# Send 0.02 BNB (native token) to an address
+baw wallet send --amount 0.02 --recipient 0x1234...5678 --binanceChainId 56 --tokenAddress 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE --json
+
+# Send 10 USDT to an address
+baw wallet send --amount 10 --recipient 0x1234...5678 --binanceChainId 56 --tokenAddress 0x55d398326f99059fF775485246999027B3197955 --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": { "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }
+}
+```
+
+### Important: a tx hash does not mean on-chain confirmation
+
+A successful response with a `txHash` means the transaction has been **broadcast** to the network — it does **not** mean it has been confirmed or finalized on-chain. Transactions can still fail after broadcast.
+
+After receiving a `txHash`, always tell the user:
+1. The transaction has been submitted and is **pending** confirmation.
+2. They can track its status with `wallet tx-history`.
+3. They should wait for on-chain confirmation before considering the transfer complete.
+
+### Address Book
+
+The `--recipient` address **must** be in the address book. To add an address, open Binance App → Wallet → Settings → Address Book.