xapi-to 0.1.20 → 0.1.22

package/skills/xapi/guides/binance_web3.md

@@ -0,0 +1,210 @@
+# Binance Web3 API Guide
+
+The official `Binance Web3 API` service uses the action prefix
+`binance-web3-api.` and currently exposes 58 Crypto actions for market data,
+address analytics, RWA data, DEX aggregation, wallet balances, transaction
+data/building/broadcast, and DeFi data and transaction building.
+
+Do not confuse it with `binance-web3.` (Binance Web3 Intelligence) or
+`binance-spot.` (Binance Spot). They are separate services with different
+actions, schemas, and upstream behavior.
+
+## Discovery and shared limit
+
+Discover the service ID instead of persisting a database UUID in automation:
+
+```bash
+npx xapi-to services --category Crypto --page-size 100
+npx xapi-to list --source api \
+  --service-id <binance-web3-api-service-id> --page-size 100
+npx xapi-to get binance-web3-api.api_v1_dex_market_token_search
+```
+
+The live catalog currently declares a service-level limit of **10 requests per
+second per user**, shared across every API key and all 58 endpoints. Pace the
+combined workload, not each action independently. The current fixed listed
+price is `$0/call`; re-check `get` because limits and pricing can change.
+
+GET actions take `{"method":"GET","params":{...}}` (plus `pathParams` when
+the schema requires them). Chain identifiers are Binance IDs such as `"1"`
+for Ethereum, `"56"` for BSC, and `"CT_501"` for Solana. They are not the
+BlockPI network names or the built-in `crypto.*` chain enum.
+
+## Safe read examples
+
+Discover the current chain list before relying on remembered IDs:
+
+```bash
+npx xapi-to call binance-web3-api.api_v1_dex_market_supported_chain \
+  --input '{"method":"GET"}'
+```
+
+Search by symbol/address, then use the returned contract and chain ID:
+
+```bash
+npx xapi-to call binance-web3-api.api_v1_dex_market_token_search --input '{
+  "method":"GET","params":{"chains":"1,56,CT_501","search":"USDT"}
+}'
+
+npx xapi-to call binance-web3-api.api_v1_dex_market_candles --input '{
+  "method":"GET","params":{
+    "binanceChainId":"1",
+    "tokenContractAddress":"0xdac17f958d2ee523a2206206994597c13d831ec7",
+    "bar":"1h","limit":100
+  }
+}'
+```
+
+`candles.limit` is currently 1–300. `before` and `after` are exclusive Unix
+millisecond bounds. Read each endpoint's enum independently; for example,
+portfolio `timeFrame` values differ from leaderboard values.
+
+RWA search supports ticker, company name, or contract address:
+
+```bash
+npx xapi-to call binance-web3-api.api_v1_dex_market_rwa_search --input '{
+  "method":"GET","params":{"keyword":"NVDA","platformId":"ondo"}
+}'
+```
+
+`platformId` currently accepts `ondo` or `bstock` and is optional.
+
+## Quote and transaction boundary
+
+Aggregator quote amounts are positive integer strings in the sell token's
+smallest unit. A quote is not a swap and does not authorize signing:
+
+```bash
+npx xapi-to call binance-web3-api.api_v1_dex_aggregator_quote --input '{
+  "method":"GET","params":{
+    "amount":"1000000","binanceChainId":"56",
+    "fromTokenAddress":"0x55d398326f99059fF775485246999027B3197955",
+    "toTokenAddress":"0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
+  }
+}'
+```
+
+The normal flow is `quote` → choose a returned route/`quoteId` (about 30-second
+TTL) → `swap` to build transaction data. `quote-and-swap` combines the first
+two steps when a vendor is selected. EVM approvals and swaps, Solana compiled
+transactions/instructions, RFQ typed data, and DeFi transaction endpoints
+return data for the caller to inspect, sign, and submit. They do not authorize
+xAPI or an agent to sign on the user's behalf.
+
+Before any sign or broadcast step, obtain explicit approval for the selected
+chain, wallet, token addresses, exact amounts, route/vendor, slippage, fees,
+approval allowance, recipient, gas policy, and expected transaction effects.
+Never pass a private key or seed phrase to xAPI.
+
+## Current POST schema gap
+
+At the time this guide was verified, the serving XAPI action catalog omitted
+the `body` from all 18 body-bearing POST operations even though the provider's
+current import payload contained those schemas. The nineteenth POST operation,
+`token_basic-info`, is intentionally query-only and exposes required `params`
+(`binanceChainId` and `tokenContractAddress`). This mismatch is serving-contract
+drift, not evidence that the official operations take no input.
+
+Do not copy a Binance-native request body or invent a `body`. For an action that
+needs request content, wait until `npx xapi-to get <action-id>` exposes it and
+report the service-schema gap instead. The query-only token basic-info action
+may be called exactly as its live `params` schema declares. Once fixed, the
+live xAPI schema—not this snapshot—is authoritative.
+
+## Provider errors
+
+Binance may return a successful HTTP response with a nonzero business code.
+Treat `code: 0` as success and preserve the upstream code/message on failure.
+In particular:
+
+- `40304` means a regional compliance restriction; changing parameters or
+  retrying cannot bypass it.
+- `40104` means the configured upstream API key lacks permission for that
+  product; DeFi access requires explicit enablement.
+
+Do not automatically retry either error or misreport it as an xAPI-key failure.
+
+## Current action catalog (58)
+
+### General Data (13)
+
+- `binance-web3-api.api_v1_dex_market_candles`
+- `binance-web3-api.api_v1_dex_market_memepump_tokenDevInfo`
+- `binance-web3-api.api_v1_dex_market_price`
+- `binance-web3-api.api_v1_dex_market_price-info`
+- `binance-web3-api.api_v1_dex_market_supported_chain`
+- `binance-web3-api.api_v1_dex_market_token_advanced-info`
+- `binance-web3-api.api_v1_dex_market_token_basic-info`
+- `binance-web3-api.api_v1_dex_market_token_holder`
+- `binance-web3-api.api_v1_dex_market_token_hot-token`
+- `binance-web3-api.api_v1_dex_market_token_search`
+- `binance-web3-api.api_v1_dex_market_token_top-liquidity`
+- `binance-web3-api.api_v1_dex_market_token_top-trader`
+- `binance-web3-api.api_v1_dex_market_trades`
+
+### Address Portfolio (7)
+
+- `binance-web3-api.api_v1_dex_market_address-tracker_trades`
+- `binance-web3-api.api_v1_dex_market_leaderboard_list`
+- `binance-web3-api.api_v1_dex_market_portfolio_dex-history`
+- `binance-web3-api.api_v1_dex_market_portfolio_overview`
+- `binance-web3-api.api_v1_dex_market_portfolio_recent-pnl`
+- `binance-web3-api.api_v1_dex_market_portfolio_supported_chain`
+- `binance-web3-api.api_v1_dex_market_portfolio_token_latest-pnl`
+
+### RWA Data (6)
+
+- `binance-web3-api.api_v1_dex_market_rwa_platforms`
+- `binance-web3-api.api_v1_dex_market_rwa_price`
+- `binance-web3-api.api_v1_dex_market_rwa_search`
+- `binance-web3-api.api_v1_dex_market_rwa_tokens`
+- `binance-web3-api.api_v1_dex_market_rwa_underlying-market`
+- `binance-web3-api.api_v1_dex_market_rwa_underlying-profile`
+
+### Trading API (9)
+
+- `binance-web3-api.api_v1_dex_aggregator_approve-transaction`
+- `binance-web3-api.api_v1_dex_aggregator_history`
+- `binance-web3-api.api_v1_dex_aggregator_order_{orderId}`
+- `binance-web3-api.api_v1_dex_aggregator_quote`
+- `binance-web3-api.api_v1_dex_aggregator_quote-and-swap`
+- `binance-web3-api.api_v1_dex_aggregator_supported_chain`
+- `binance-web3-api.api_v1_dex_aggregator_swap`
+- `binance-web3-api.api_v1_dex_aggregator_swap-instruction`
+- `binance-web3-api.api_v1_dex_aggregator_order_submit`
+
+### Transaction API (7)
+
+- `binance-web3-api.api_v1_dex_post-transaction_orders`
+- `binance-web3-api.api_v1_dex_pre-transaction_block-height`
+- `binance-web3-api.api_v1_dex_pre-transaction_broadcast-transaction`
+- `binance-web3-api.api_v1_dex_pre-transaction_gas-limit`
+- `binance-web3-api.api_v1_dex_pre-transaction_gas-price`
+- `binance-web3-api.api_v1_dex_pre-transaction_simulate`
+- `binance-web3-api.api_v1_dex_pre-transaction_supported_chain`
+
+### Wallet API (5)
+
+- `binance-web3-api.api_v1_dex_balance_all-token-balances-by-address`
+- `binance-web3-api.api_v1_dex_balance_supported_chain`
+- `binance-web3-api.api_v1_dex_balance_token-balances-by-address`
+- `binance-web3-api.api_v1_dex_post-transaction_transaction-detail-by-txhash`
+- `binance-web3-api.api_v1_dex_post-transaction_transactions-by-address`
+
+### DeFi Data and Transaction (11)
+
+- `binance-web3-api.api_v1_defi_data_investment_detail`
+- `binance-web3-api.api_v1_defi_data_investment_list`
+- `binance-web3-api.api_v1_defi_data_position_list`
+- `binance-web3-api.api_v1_defi_data_protocol_detail`
+- `binance-web3-api.api_v1_defi_data_protocol_list`
+- `binance-web3-api.api_v1_defi_transaction_claim`
+- `binance-web3-api.api_v1_defi_transaction_deposit`
+- `binance-web3-api.api_v1_defi_transaction_lp-add`
+- `binance-web3-api.api_v1_defi_transaction_lp-add_calculate`
+- `binance-web3-api.api_v1_defi_transaction_lp-remove`
+- `binance-web3-api.api_v1_defi_transaction_redeem`
+
+Use `list --service-id` to detect additions/removals and `get` immediately
+before each call. Do not infer that similarly named endpoints share parameters,
+enum values, pagination, or response shapes.

package/skills/xapi/guides/blockpi.md

@@ -0,0 +1,112 @@
+# BlockPI RPC Guide
+
+The `rpc` third-party service exposes EVM JSON-RPC through BlockPI. The current
+catalog has one generic action and 12 legacy convenience actions over 60
+explicitly registered mainnets and testnets. The server supplies the BlockPI
+partner credential; callers send only their xAPI key to xAPI and must never ask for, expose, or forward the upstream credential.
+
+Always inspect the live schema and price before calling:
+
+```bash
+npx xapi-to get rpc.network
+npx xapi-to search "BlockPI RPC" --source api --page-size 100
+```
+
+The catalog currently lists each action at `$0.000003/call`; treat `get` as the
+authority because pricing and supported networks may change.
+
+## Generic JSON-RPC
+
+Prefer `rpc.network` for arbitrary EVM methods. It accepts exactly one JSON-RPC
+request object, not a batch. Keep the HTTP method and JSON-RPC method separate:
+
+```bash
+npx xapi-to call rpc.network --input '{
+  "method":"POST",
+  "pathParams":{"network":"ethereum"},
+  "body":{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}
+}'
+```
+
+The required outer fields are `method`, `pathParams`, and `body`.
+`pathParams.network` selects the registered BlockPI network. The body requires
+`jsonrpc: "2.0"` and the JSON-RPC `method`; `id` and `params` are optional.
+
+The generic route fails closed with HTTP 503 when the server-side partner key
+is unavailable; it never silently sends a raw RPC call without that credential.
+The legacy convenience routes have a different availability contract and may
+fall back to their configured public RPC endpoints. Diagnose the two route
+families separately instead of treating every BlockPI 503 as a bad request.
+
+For example, read an address balance without exposing any provider key:
+
+```bash
+npx xapi-to call rpc.network --input '{
+  "method":"POST",
+  "pathParams":{"network":"base"},
+  "body":{"jsonrpc":"2.0","id":"balance-1","method":"eth_getBalance",
+          "params":["0x0000000000000000000000000000000000000000","latest"]}
+}'
+```
+
+## Registered networks
+
+The current `rpc.network` enum contains 60 values:
+
+```text
+abstract, arbitrum, arbitrum-nova, arbitrum-sepolia, arc-testnet,
+avalanche, avalanche-fuji, base, base-sepolia, berachain, blast, bsc,
+bsc-testnet, celo, celo-sepolia, conflux-espace, cronos, ethereum,
+ethereum-hoodi, ethereum-sepolia, etherlink, fantom, gnosis, hemi,
+hyperliquid, ink, kaia, kaia-kairos, linea, linea-sepolia, mantle, merlin,
+merlin-testnet, meter, metis, monad, monad-testnet, optimism,
+optimism-sepolia, plasma, plume, polygon, polygon-amoy, robinhood, scroll,
+scroll-sepolia, sei-evm, sei-testnet-evm, sonic, stable, story, taiko,
+unichain, unichain-sepolia, viction, xlayer, zetachain-athens-evm,
+zetachain-evm, zksync-era, zksync-era-sepolia
+```
+
+Do not normalize or invent aliases. Re-run `get rpc.network` and use its exact
+enum when a network is absent or when the task depends on current support.
+
+## Legacy convenience actions
+
+These actions translate simple REST-shaped inputs to common EVM methods:
+
+- `rpc.network` — arbitrary single JSON-RPC request
+- `rpc.chain_blockNumber` — latest block number
+- `rpc.chain_call` — `eth_call`
+- `rpc.chain_chainId` — chain ID
+- `rpc.chain_gasPrice` — gas price
+- `rpc.chain_getBalance` — native balance
+- `rpc.chain_getBlockByHash` — block by hash
+- `rpc.chain_getBlockByNumber` — block by number/tag
+- `rpc.chain_getCode` — contract bytecode
+- `rpc.chain_getLogs` — event logs
+- `rpc.chain_getTransactionByHash` — transaction by hash
+- `rpc.chain_getTransactionCount` — address nonce
+- `rpc.chain_getTransactionReceipt` — transaction receipt
+
+Legacy actions use `pathParams.chain` plus action-specific query `params`.
+Never infer those parameters from the raw JSON-RPC signature; inspect the exact
+action first:
+
+```bash
+npx xapi-to get rpc.chain_getBalance
+npx xapi-to call rpc.chain_getBalance --input '{
+  "method":"POST",
+  "pathParams":{"chain":"ethereum"},
+  "params":{"address":"0x0000000000000000000000000000000000000000",
+            "block":"latest"}
+}'
+```
+
+## Transaction safety
+
+Reads such as block, balance, code, logs, and receipt queries are non-mutating.
+Methods such as `eth_sendRawTransaction` can create irreversible on-chain
+effects even though they use the same generic action. Before submitting a
+signed transaction, obtain explicit approval for the chain, sender, recipient,
+value, calldata, gas policy, and transaction hash workflow. Do not send private
+keys or seed phrases through xAPI, and do not automatically retry an ambiguous
+broadcast. Check the transaction hash or sender nonce first.

package/skills/xapi/guides/domains.md

@@ -0,0 +1,189 @@
+# Domains and DNS Guide
+
+Use the built-in `domain.*` and `dns.*` capabilities to search, price, register,
+list, and inspect domains, then manage their DNS records. These are capability
+actions, not third-party API actions, so discover them with
+`--source capability` and pass a flat JSON object to `--input`.
+
+Domain registration is a real, non-refundable purchase. DNS changes alter live
+traffic. Read the current schema, show the user the exact target and price or
+record change, and obtain explicit approval before either mutation.
+
+## Current actions
+
+| Action | Purpose | Mutation |
+|---|---|---|
+| `domain.search` | Registrar suggestions and one-year estimated prices | No |
+| `domain.check` | Check exact-domain availability | No |
+| `domain.price` | Read the current USD registration price | No |
+| `domain.register` | Register a domain | **Purchase** |
+| `domain.registration.get` | Read an asynchronous registration task | No |
+| `domain.list` | List domains owned through xAPI | No |
+| `domain.get` | Inspect one domain by `domain_id` | No |
+| `dns.list` | List a domain's DNS records | No |
+| `dns.upsert` | Create or update a DNS record | **Write** |
+| `dns.delete` | Delete a DNS record | **Write** |
+| `dns.dnssec.get` | Read desired, effective, and provider DNSSEC state | No |
+| `dns.dnssec.set` | Enable or disable Cloudflare DNSSEC | **Write** |
+
+Fetch the live schemas before use:
+
+```bash
+npx xapi-to get-batch domain.search domain.check domain.price domain.register \
+  domain.registration.get domain.list domain.get dns.list dns.upsert dns.delete \
+  dns.dnssec.get dns.dnssec.set
+```
+
+## Search, check, and price
+
+`domain.search` accepts a keyword and up to 20 optional TLDs. Its availability
+and one-year prices are suggestions, not a purchase quote. Search first, then
+check and price the exact fully qualified domain:
+
+```bash
+npx xapi-to call domain.search \
+  --input '{"keyword":"example","tlds":["com","dev","ai"]}'
+
+npx xapi-to call domain.check --input '{"domain":"example.com"}'
+npx xapi-to call domain.price --input '{"domain":"example.com","period":1}'
+```
+
+`domain.price` is the authoritative pre-registration price at call time. The
+current USD billable price includes xAPI's fixed fee; non-USD registrar quotes
+are unsupported. Re-price immediately before registration because availability
+and upstream prices can change.
+
+## Register a domain
+
+Before calling `domain.register`:
+
+1. Re-run `domain.check` and `domain.price` for the exact domain and period.
+2. Show the exact domain, period, current USD price, and `max_price_usd` ceiling.
+3. Confirm the registrant contact details and obtain explicit purchase approval.
+4. Create one idempotency key for that exact request and reuse it only for retries.
+
+The required contact fields are `first_name`, `last_name`, `address1`, `city`,
+`state`, `postal_code`, `country`, `phone`, and `email`. `country` is a two-letter
+ISO code. Phone numbers must use `+{country_code}.{number}`, for example
+`+86.13800138000`. Do not log contact data or include it in task summaries.
+
+```bash
+npx xapi-to call domain.register --input '{
+  "domain":"example.com",
+  "period":1,
+  "max_price_usd":20,
+  "idempotency_key":"register-example-com-20260910",
+  "auto_renew":false,
+  "whois_privacy":true,
+  "contact":{
+    "first_name":"Given","last_name":"Family",
+    "address1":"Street address","city":"City","state":"Region",
+    "postal_code":"000000","country":"CN",
+    "phone":"+86.13800138000","email":"owner@example.com"
+  }
+}'
+```
+
+`max_price_usd` is a hard final-charge ceiling, not the expected price.
+`auto_renew` must currently remain `false`; renewal billing is not available.
+Registration is non-refundable. A successful submission can return a `task_id`
+before the registrar has finished. Poll that exact task rather than repeating the
+purchase:
+
+```bash
+npx xapi-to call domain.registration.get \
+  --input '{"task_id":"<task-id-from-domain-register>"}'
+```
+
+Continue polling only while `status` is `pending` or `processing`. Treat
+`succeeded`, `failed`, and `expired` as terminal. Preserve `phase`, `action`,
+`error`, `final_cost`, and `confirmation_sent_to` when reporting the result;
+some registrations can require external confirmation or manual review.
+
+Do not retry with a new idempotency key after an ambiguous response. If a
+`task_id` was returned, read it with `domain.registration.get`. Otherwise reuse
+the original key only for the exact same request, then inspect `domain.list`
+before deciding whether another purchase attempt is safe.
+
+`domain.get` intentionally does not return the registrant contact. Treat that
+privacy boundary as expected rather than assuming registration lost the data.
+
+## DNS workflow
+
+DNS actions use the xAPI `domain_id`, not the domain name. Resolve it with
+`domain.list`, inspect the current records, and retain the stable `record_id`:
+
+```bash
+npx xapi-to call domain.list --input '{"limit":50,"offset":0}'
+npx xapi-to call dns.list --input '{"domain_id":"<domain-id>"}'
+```
+
+Create a record by omitting both record identifiers:
+
+```bash
+npx xapi-to call dns.upsert --input '{
+  "domain_id":"<domain-id>",
+  "subdomain":"@","type":"A","value":"203.0.113.10",
+  "idempotency_key":"dns-create-root-a-20260910"
+}'
+```
+
+Update an existing record with its stable `record_id`. `record_index` is a
+legacy fallback whose meaning can change when the record set changes; use it
+only when a live response lacks `record_id`.
+
+```bash
+npx xapi-to call dns.upsert --input '{
+  "domain_id":"<domain-id>","record_id":"<record-id>",
+  "subdomain":"www","type":"CNAME","value":"example.com.",
+  "idempotency_key":"dns-update-www-20260910"
+}'
+
+npx xapi-to call dns.delete --input '{
+  "domain_id":"<domain-id>","record_id":"<record-id>",
+  "idempotency_key":"dns-delete-record-20260910"
+}'
+```
+
+For every write, confirm the domain, record type/name/value, and stable record
+identifier. Reuse an idempotency key only for an identical retry; use a new key
+when any requested value changes. After a successful write, call `dns.list`
+again and verify the intended state instead of assuming propagation or success.
+
+## DNSSEC lifecycle
+
+DNSSEC is currently available only for domains whose authoritative provider is
+Cloudflare. Read the current state before changing it:
+
+```bash
+npx xapi-to call dns.dnssec.get \
+  --input '{"domain_id":"<domain-id>"}'
+```
+
+After explicit approval, request the desired state with one stable idempotency
+key. Reuse that key only when retrying this exact domain and `enabled` value:
+
+```bash
+npx xapi-to call dns.dnssec.set --input '{
+  "domain_id":"<domain-id>",
+  "enabled":true,
+  "idempotency_key":"dnssec-enable-example-20260917"
+}'
+```
+
+The mutation can finish its request while Cloudflare or the parent registry is
+still reconciling. Interpret the response fields together:
+
+- `desired_enabled` is the requested target.
+- `effective_enabled` is the state currently protecting DNS responses.
+- `transition` is `enabling`, `disabling`, or `null` when settled.
+- `provider_status` preserves the upstream lifecycle state.
+- `action_required` means operator intervention is needed.
+
+`pending` and `pending-disabled` are transitions, not success. Poll
+`dns.dnssec.get` until the state settles, becomes `error`, or the user's
+deadline is reached. Do not report DNSSEC as enabled until
+`effective_enabled=true` with no transition, and do not report it as disabled
+until `effective_enabled=false` with no transition. Preserve DS metadata when
+the caller needs to inspect delegation, but never invent or manually publish a
+DS record unless the live response explicitly says operator action is required.