skillpp 0.1.0

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

@@ -0,0 +1,86 @@
+# Wallet Settings
+
+View the wallet's current security configuration and daily quota. Settings can only be changed in the Binance App — this command is read-only.
+
+## `wallet settings`
+
+### Syntax
+
+```bash
+baw wallet settings --json
+```
+
+### Parameters
+
+No command-specific parameters.
+
+### Example
+
+```bash
+baw wallet settings --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "maxSigninDuration": "48h",
+    "inactiveSignoutDuration": "24h",
+    "dailyLimit": 50000,
+    "abnormalTxnHandling": "AutoReject",
+    "tradeAllTokens": false,
+    "predictionEnabled": true,
+    "predictionDailyLimit": 50000,
+    "predictionQuotaUsed": 0,
+    "predictionQuotaLeft": 50000,
+    "predictionQuotaDate": "2026-04-03",
+    "x402DailyLimit": 20,
+    "x402QuotaUsed": 0,
+    "x402QuotaLeft": 20,
+    "x402QuotaDate": "2026-04-03",
+    "quotaUsed": 0,
+    "quotaLeft": 50000,
+    "quotaDate": "2026-04-03",
+    "inactiveSignOutTime": "2026-04-04T06:32:05+08:00",
+    "sessionExpireTime": "2026-04-04T06:32:05+08:00"
+  }
+}
+```
+
+Returns the current security settings:
+- **maxSigninDuration** — The maximum time the Agentic Wallet can stay signed in before the Agent is automatically signed out.
+- **inactiveSignoutDuration** — The Agent will be signed out after this period of inactivity, regardless of the Max Sign-In Duration. Currently fixed at 24 hours and not user-configurable.
+- **dailyLimit** — maximum total transaction value allowed in a 24-hour period.
+- **abnormalTxnHandling** — How the wallet handles transactions flagged as high-risk or with abnormal price impact. Only two values are possible:
+    - `AutoReject` — automatically block abnormal transactions without prompting the user.
+    - `NeedConfirmation` — send a double-confirm request to the Binance App and wait for the user to approve or reject.
+- **tradeAllTokens** — whether the wallet can trade any token or only those on the allowed list.
+- **predictionEnabled** — whether prediction-market trading (see [`prediction`](./prediction.md) commands) is enabled for this wallet. When `false`, `prediction trade *` calls will be rejected by policy.
+- **predictionDailyLimit** — maximum total prediction-trade value (in USD) allowed in a 24-hour period. **Independent from `dailyLimit`**: prediction trades only consume `predictionQuotaUsed`.
+- **x402DailyLimit** — maximum total x402 payment value (in USD) allowed in a 24-hour period. **Independent from `dailyLimit` and `predictionDailyLimit`**: x402 payments only consume `x402QuotaUsed`.
+
+The response also includes current status information:
+- **quotaUsed** — how much of the daily limit (in USD) has been consumed so far today.
+- **quotaLeft** — remaining daily limit (in USD) available for transactions today.
+- **quotaDate** — the date these quota figures apply to.
+- **predictionQuotaUsed** — how much of `predictionDailyLimit` has been consumed by prediction trades today.
+- **predictionQuotaLeft** — remaining prediction-trade quota available today.
+- **predictionQuotaDate** — the date these prediction-quota figures apply to.
+- **x402QuotaUsed** — how much of the x402 daily limit (in USD) has been consumed so far today.
+- **x402QuotaLeft** — remaining x402 daily limit (in USD) available for x402 payments today.
+- **x402QuotaDate** — the date these x402 quota figures apply to.
+- **inactiveSignOutTime** - when the agent will sign out due to the inactive signout duration settings.
+- **sessionExpireTime** — when the current session will expire and the wallet will automatically sign out.
+
+### Changing Settings
+
+Settings cannot be changed via the CLI. To update them, follow these steps in the Binance App:
+
+1. Open the **Binance Wallet App**.
+2. Navigate to the **Agentic Wallet** management page.
+3. Tap the **settings icon** in the top-right corner to enter wallet Settings.
+4. Adjust the desired security settings.
+
+When a transaction is rejected because of a security policy (e.g., token not on the allowed list, daily limit exceeded, x402 daily limit exceeded, prediction disabled, prediction daily limit exceeded), use `wallet settings` to explain the restriction and guide the user to the App to make adjustments.

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

@@ -0,0 +1,312 @@
+# Wallet View Commands
+
+## `wallet status`
+
+Check the current authentication and wallet state.
+
+### Syntax
+
+```bash
+baw wallet status --json
+```
+
+### Parameters
+
+No command-specific parameters.
+
+### Example
+
+```bash
+baw wallet status --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "status": "CONNECTED"
+  }
+}
+```
+
+| Status        | Meaning                        |
+|---------------|--------------------------------|
+| `UNCONNECTED` | Not signed in                  |
+| `CREATING`    | Signed in; wallet being set up |
+| `CONNECTED`   | Signed in; wallet ready to use |
+
+---
+
+## `wallet chains`
+
+List the blockchain networks the wallet currently supports.
+
+### Syntax
+
+```bash
+baw wallet chains --json
+```
+
+### Parameters
+
+No command-specific parameters.
+
+### Example
+
+```bash
+baw wallet chains --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": [
+    { "binanceChainId": "56", "name": "BNB Smart Chain", "simpleName": "BSC" }
+  ]
+}
+```
+
+---
+
+## `wallet address`
+
+Retrieve the wallet addresses.
+
+### Syntax
+
+```bash
+baw wallet address --json
+```
+
+### Parameters
+
+No command-specific parameters.
+
+### Example
+
+```bash
+baw wallet address --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "addresses": [
+      {
+        "binanceChainId": "CT_501",
+        "chainName": "Solana",
+        "address": "E...S"
+      },
+      {
+        "binanceChainId": "1",
+        "chainName": "Ethereum",
+        "address": "0x1234...5678"
+      },
+      {
+        "binanceChainId": "56",
+        "chainName": "BSC",
+        "address": "0x1234...5678"
+      },
+      {
+        "binanceChainId": "8453",
+        "chainName": "Base",
+        "address": "0x1234...5678"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## `wallet balance`
+
+Query token balances. Only tokens with a value of at least $0.01 USD are returned; tokens worth less than $0.01 are hidden by CLI.
+
+### Syntax
+
+```bash
+baw wallet balance [--symbol <symbol>] [--tokenAddress <tokenAddress>] [--binanceChainId <binanceChainId>] --json
+```
+
+### Parameters
+
+| Parameter          | Required | Default | Description                                                                           |
+|--------------------|----------|---------|---------------------------------------------------------------------------------------|
+| `--symbol`         | No       | —       | Filter by token symbol (e.g., `BNB`, `USDT`, `USDC`)                                  |
+| `--tokenAddress`   | No       | —       | Filter by token contract address                                                      |
+| `--binanceChainId` | No       | —       | Binance chain ID: `56` (BSC), `CT_501` (Solana). For a full list, see `wallet chains` |
+
+### Example
+
+```bash
+# Query all balances
+baw wallet balance --json
+
+# Query USDT balance only
+baw wallet balance --symbol USDT --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": [
+    { "symbol": "USDT", "address": "0x55d398326f99059fF775485246999027B3197955", "binanceChainId": "56", "balance": "1000.50", "price": "1.0", "value": "1000.50" }
+  ]
+}
+```
+
+---
+
+## `wallet tx-history`
+
+Retrieve transaction history with optional filtering and pagination.
+
+### Syntax
+
+```bash
+baw wallet tx-history [--type <type>] [--size <size>] [--nextCursor <nextCursor>] [--tx <tx>] [--startTime <startTime>] [--endTime <endTime>] [--binanceChainId <binanceChainId>] --json
+```
+
+### Parameters
+
+| Parameter          | Required | Default      | Description                                                                           |
+|--------------------|----------|--------------|---------------------------------------------------------------------------------------|
+| `--type`           | No       | `all`        | `all`, `pending`, `confirmed`                                                         |
+| `--size`           | No       | `20`         | Results per page (max 100)                                                            |
+| `--nextCursor`     | No       | —            | Pagination cursor from a previous response                                            |
+| `--tx`             | No       | —            | Look up a single transaction by hash                                                  |
+| `--startTime`      | No       | 3 months ago | Start time (ms timestamp)                                                             |
+| `--endTime`        | No       | —            | End time (ms timestamp)                                                               |
+| `--binanceChainId` | No       | —            | Binance chain ID: `56` (BSC), `CT_501` (Solana). For a full list, see `wallet chains` |
+
+### Example
+
+```bash
+# Query recent transactions
+baw wallet tx-history --json
+
+# Query pending transactions
+baw wallet tx-history --type pending --json
+
+# Look up a specific transaction
+baw wallet tx-history --tx 0xabc123... --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "transactions": [
+      {
+        "txType": "swap",
+        "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "txTime": "2026-04-01T09:05:30+08:00",
+        "binanceChainId": "56",
+        "status": "confirmed",
+        "txHashList": [
+          {
+            "binanceChainId": "56",
+            "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+            "status": "confirmed",
+            "networkFee": {
+              "binanceChainId": "56",
+              "feeTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+              "feeTokenSymbol": "BNB",
+              "feeValue": "0",
+              "feeTokenDecimals": 18
+            },
+            "instructions": {
+              "send": [
+                {
+                  "binanceChainId": "56",
+                  "amount": "1000000000000000000",
+                  "addressInfo": { "address": "0x1234...5678" },
+                  "tokenInfo": {
+                    "binanceChainId": "56",
+                    "contractAddress": "0xcaca...1231",
+                    "symbol": "Token1",
+                    "tokenId": null,
+                    "decimals": 18
+                  }
+                }
+              ],
+              "receive": [
+                {
+                  "binanceChainId": "56",
+                  "amount": "1000000000000000000",
+                  "addressInfo": { "address": "0x1234...5678" },
+                  "tokenInfo": {
+                    "binanceChainId": "56",
+                    "contractAddress": "0xcaca...1232",
+                    "symbol": "Token2",
+                    "tokenId": null,
+                    "decimals": 18
+                  }
+                }
+              ]
+            }
+          }
+        ]
+      }
+    ],
+    "hasMore": true,
+    "nextCursor": "__CONFIRMED__:1234567890"
+  }
+}
+```
+
+---
+
+## `wallet tx-lock`
+
+Check whether the wallet is currently locked from sending new transactions.
+
+### Syntax
+
+```bash
+baw wallet tx-lock --binanceChainId <binanceChainId> --json
+```
+
+### Parameters
+
+| Parameter          | Required | Default      | Description                                                                           |
+|--------------------|----------|--------------|---------------------------------------------------------------------------------------|
+| `--binanceChainId` | Yes      | —            | Binance chain ID: `56` (BSC), `CT_501` (Solana). For a full list, see `wallet chains` |
+
+### Example
+
+```bash
+baw wallet tx-lock --binanceChainId 56 --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "status": "UNLOCKED"
+  }
+}
+```
+
+| Status     | Meaning                                                                                                                                                   |
+|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `UNLOCKED` | The wallet is free to send new transactions.                                                                                                              |
+| `LOCKED`   | A transaction is pending on-chain, or a double-confirm request is waiting in the Binance App. The user must resolve it before starting a new transaction. |
+
+The wallet becomes locked in two situations:
+1. **Transaction pending on-chain** — a previously submitted transaction has not yet been confirmed on the blockchain. Nothing to do but wait; re-check with `wallet tx-lock` after a short while.
+2. **Double-confirm pending** — the transaction triggered a risk-control check (either the token is flagged as risky, or a DEX swap has excessive price deviation). Tell the user to open the Binance App to approve or reject it (5-minute timeout).

package/skills/binance-web3/binance-agentic-wallet/references/x402-payment.md

@@ -0,0 +1,259 @@
+# x402 Payment
+
+Pay for an x402 HTTP resource by previewing payment options, then signing one.
+
+## `x402-payment preview`
+
+Preview payment options from a Merchant's `PaymentRequired` response.
+
+### Syntax
+
+```bash
+baw x402-payment preview --paymentRequirements <base64-or-raw-json> --json
+```
+
+### Parameters
+
+| Parameter               | Required | Description                                                                                        |
+|-------------------------|----------|----------------------------------------------------------------------------------------------------|
+| `--paymentRequirements` | Yes      | The `PaymentRequired` payload — either the base64 `PAYMENT-REQUIRED` header value or its raw JSON. |
+
+### Example
+
+```bash
+baw x402-payment preview --paymentRequirements '{
+  "x402Version": 2,
+  "resource": {"url": "https://merchant/api"},
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "eip155:8453",
+      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "amount": "10000000",
+      "payTo": "0x1111111111111111111111111111111111111111",
+      "extra": {"name": "USD Coin", "version": "2"}
+    },
+    {
+      "scheme": "exact",
+      "network": "eip155:56",
+      "asset": "0x55d398326f99059fF775485246999027B3197955",
+      "amount": "10000000000000000000",
+      "payTo": "0x1111111111111111111111111111111111111111",
+      "extra": {"name": "Tether USD", "version": "1"}
+    },
+    {
+      "scheme": "exact",
+      "network": "eip155:42161",
+      "asset": "0xcaca...1231",
+      "amount": "10000000",
+      "payTo": "0x1111111111111111111111111111111111111111",
+      "extra": {"name": "USD Coin", "version": "2"}
+    }
+  ]
+}' --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "paymentId": "550e8400-e29b-41d4-a716-446655440000",
+    "options": [
+      {
+        "index": 1,
+        "status": "READY_TO_SIGN",
+        "reasons": [],
+        "scheme": "exact",
+        "assetTransferMethod": "eip3009",
+        "binanceChainId": "8453",
+        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "tokenSymbol": "USDC",
+        "amount": "10",
+        "amountUsd": "10.00",
+        "payTo": "0x1111111111111111111111111111111111111111",
+        "userWalletAddress": "0x2222222222222222222222222222222222222222",
+        "currentBalance": "100",
+        "currentBalanceUsd": "100.00",
+        "needApproveFirst": false,
+        "originalAccept": {
+          "scheme": "exact",
+          "network": "eip155:8453",
+          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+          "amount": "10000000",
+          "payTo": "0x1111111111111111111111111111111111111111",
+          "extra": {
+            "name": "USD Coin",
+            "version": "2"
+          }
+        }
+      },
+      {
+        "index": 2,
+        "status": "ACTION_REQUIRED",
+        "reasons": [
+          "INSUFFICIENT_BALANCE"
+        ],
+        "scheme": "exact",
+        "assetTransferMethod": "eip3009",
+        "binanceChainId": "56",
+        "tokenAddress": "0x55d398326f99059fF775485246999027B3197955",
+        "tokenSymbol": "USDT",
+        "amount": "10",
+        "amountUsd": "10.01",
+        "payTo": "0x1111111111111111111111111111111111111111",
+        "userWalletAddress": "0x2222222222222222222222222222222222222222",
+        "currentBalance": "1.5",
+        "currentBalanceUsd": "1.50",
+        "needApproveFirst": false,
+        "originalAccept": {
+          "scheme": "exact",
+          "network": "eip155:56",
+          "asset": "0x55d398326f99059fF775485246999027B3197955",
+          "amount": "10000000000000000000",
+          "payTo": "0x1111111111111111111111111111111111111111",
+          "extra": {
+            "name": "Tether USD",
+            "version": "1"
+          }
+        }
+      },
+      {
+        "index": 3,
+        "status": "NOT_SIGNABLE",
+        "reasons": [
+          "UNSUPPORTED_NETWORK"
+        ],
+        "scheme": "exact",
+        "originalAccept": {
+          "scheme": "exact",
+          "network": "eip155:42161",
+          "asset": "0xcaca...1231"
+        }
+      }
+    ]
+  }
+}
+```
+
+| Field                           | Description                                                                                                                                                               |
+|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `paymentId`                     | UUID identifying this payment.                                                                                                                                            |
+| `options[].index`               | 1-based selector (first option is `1`, not `0`) to pass to `sign --selectedIndex`.                                                                                        |
+| `options[].status`              | The option's status, which drives the next step. See table below.                                                                                                         |
+| `options[].reasons`             | Reasons the option isn't ready to sign. See table below.                                                                                                                  |
+| `options[].scheme`              | x402 scheme, such as `exact`.                                                                                                                                             |
+| `options[].assetTransferMethod` | Asset transfer method, such as `eip3009`, `permit2`, `spl-transfer`, etc.                                                                                                 |
+| `options[].binanceChainId`      | Binance chain ID: `56` (BSC), `CT_501` (Solana).                                                                                                                          |
+| `options[].tokenAddress`        | Token contract address.                                                                                                                                                   |
+| `options[].tokenSymbol`         | Token symbol, e.g. `USDT`.                                                                                                                                                |
+| `options[].amount`              | Amount of tokens to pay, in human-readable units.                                                                                                                         |
+| `options[].amountUsd`           | Equivalent USD value at the current token price.                                                                                                                          |
+| `options[].payTo`               | Recipient (Merchant) address.                                                                                                                                             |
+| `options[].userWalletAddress`   | User's own wallet address on this chain.                                                                                                                                  |
+| `options[].currentBalance`      | User's current balance of `tokenAddress`, in human-readable units.                                                                                                        |
+| `options[].currentBalanceUsd`   | Equivalent USD value of `currentBalance` at the current token price.                                                                                                      |
+| `options[].needApproveFirst`    | Whether a Permit2 approve tx is required before this payment. If true, `sign` will dispatch the approve tx alongside the signature — on BSC the approve gas is sponsored. |
+| `options[].originalAccept`      | The Merchant's original accept entry.                                                                                                                                     |
+
+`options[].status` values:
+
+| Value             | Meaning                                              |
+|-------------------|------------------------------------------------------|
+| `READY_TO_SIGN`   | Can be signed directly. No user action required.     |
+| `ACTION_REQUIRED` | Can only be signed after the user takes some action. |
+| `NOT_SIGNABLE`    | Cannot be signed. Retrying won't help.               |
+
+`options[].reasons` values:
+
+| Value                         | Implied status  | Meaning                                                                                                |
+|-------------------------------|-----------------|--------------------------------------------------------------------------------------------------------|
+| `INSUFFICIENT_BALANCE`        | ACTION_REQUIRED | The user's balance of `tokenAddress` on this chain is below `amount`.                                  |
+| `INVALID_ACCEPT_STRUCTURE`    | NOT_SIGNABLE    | The Merchant's original accept structure is invalid.                                                   |
+| `UNSUPPORTED_NETWORK`         | NOT_SIGNABLE    | The accept's `network` is outside our supported set.                                                   |
+| `UNSUPPORTED_SCHEME`          | NOT_SIGNABLE    | The accept's `scheme` is outside our supported set.                                                    |
+| `UNSUPPORTED_METHOD`          | NOT_SIGNABLE    | The accept's `assetTransferMethod` is outside our supported set: `eip3009`, `permit2`, `spl-transfer`. |
+| `NO_WALLET_ON_CHAIN`          | NOT_SIGNABLE    | The user's agentic wallet has no address on this chain.                                                |
+| `BLOCKED_BY_SECURITY_CHECK`   | NOT_SIGNABLE    | Security check flagged the payment as risky.                                                           |
+| `BLOCKED_DAILY_LIMIT_REACHED` | NOT_SIGNABLE    | The user's daily x402 spending limit has been reached.                                                 |
+
+### Acting on preview result
+
+- The returned options are pre-sorted; options earlier in the list are recommended over later ones.
+- Only options with `status = READY_TO_SIGN` can be signed directly. `ACTION_REQUIRED` options can be signed after the user takes a remediation action; `NOT_SIGNABLE` options cannot be signed.
+
+---
+
+## `x402-payment sign`
+
+Sign a payment option from `preview` and return the replay x402 header.
+
+### Syntax
+
+```bash
+baw x402-payment sign --paymentId <payment-id> --selectedIndex <index> --json
+```
+
+### Parameters
+
+| Parameter         | Required | Description                                                                    |
+|-------------------|----------|--------------------------------------------------------------------------------|
+| `--paymentId`     | Yes      | The `paymentId` returned by `preview`.                                         |
+| `--selectedIndex` | Yes      | The selected option `index` returned by `preview`. Must not be `NOT_SIGNABLE`. |
+
+### Example
+
+```bash
+baw x402-payment sign --paymentId 550e8400-e29b-41d4-a716-446655440000 --selectedIndex 1 --json
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "paymentHeaderName": "PAYMENT-SIGNATURE",
+    "paymentHeaderValue": "eyJ4NDAyVmVyc2lvbiI6Mi...",
+    "approveTxHash": null,
+    "binanceChainId": null,
+    "signatureExpiresAt": 1747900800
+  }
+}
+```
+
+| Field                | Description                                                                                                         |
+|----------------------|---------------------------------------------------------------------------------------------------------------------|
+| `paymentHeaderName`  | HTTP header name to use when replaying. For x402 v2 this is always `PAYMENT-SIGNATURE`.                             |
+| `paymentHeaderValue` | HTTP header value to use when replaying. Set this as the `paymentHeaderName` header on the request to the Merchant. |
+| `approveTxHash`      | Non-null only when this sign also dispatched a Permit2 approve tx. See _Replaying the Request_.                     |
+| `binanceChainId`     | Binance chain ID where `approveTxHash` was dispatched. Null when no approve was dispatched.                         |
+| `signatureExpiresAt` | Unix epoch seconds (UTC) after which the signature is no longer valid. See _Replaying the Request_.                |
+
+---
+
+### Replaying the Request
+
+- Replay the original HTTP request with the `paymentHeaderName: paymentHeaderValue` header from `sign` attached.
+- Construct the replay request using the schema from the x402 payment requirements' `extensions` field if available.
+- If `approveTxHash` is non-null (Permit2), wait for it to confirm (e.g. `baw wallet tx-history --tx <hash>`) before replaying.
+- A signature can only be used once and is valid until `signatureExpiresAt`. If exceeded, restart from `preview`.
+- The `PAYMENT-RESPONSE` response header (base64 JSON) carries settlement metadata, including the `txHash`.
+- Infer the response body's schema before parsing it; don't parse blindly.
+
+---
+
+## Guardrails
+
+1. **Confirm before signing.** Always confirm with the user before calling `sign`; only proceed once they've consented.
+2. **Confirm before signing another payment option.** Always confirm with the user before switching to a different payment option, network, or token; only proceed once they've consented.
+3. **Confirm before changing to a new resource.** Always confirm with the user before paying for a different resource or service; never silently substitute — if the current one fails, report the error and let the user decide.
+4. **Confirm before retrying more than once.** If replaying the request fails due to a network or unknown error, retry at most once automatically. Before any further retries, confirm with the user.
+
+---
+
+## Limitations
+
+- Only x402 v2 is supported.
+- Only BSC, Base, and Solana are supported. Ethereum is not supported.