xapi-to 0.1.21 → 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.

package/skills/xapi/guides/provider.md

@@ -55,6 +55,36 @@ Use `--clear-about` or `--clear-website` to clear a value. Provider metadata
 updates cannot modify the version contract or upstream credentials; use the
 version command for those fields.
 
+## Configure a service request limit
+
+Rate limits are optional service settings. Configure both values together when
+creating a service or updating an existing one:
+
+```bash
+npx xapi-to provider create --file ./service.json \
+  --rate-limit-requests 100 \
+  --rate-limit-period-seconds 60
+
+npx xapi-to provider update <service-id> \
+  --rate-limit-requests 100 \
+  --rate-limit-period-seconds 60
+```
+
+`requests` accepts 1 through 1,000,000 and `periodSeconds` accepts 1 through
+86,400. The backend applies one quota to each User x Service pair, so all API keys
+owned by the same user share that service quota. This setting is supported only
+for `PROXY` services; the backend rejects a non-null limit for `DIRECT` services.
+
+Disable the limit explicitly with:
+
+```bash
+npx xapi-to provider update <service-id> --clear-rate-limit
+```
+
+This sends `rateLimitConfig: null`. Omitting the rate-limit flags during an
+update leaves the existing setting unchanged. A raw `rateLimitConfig` can also
+be included in `service.json`; explicit CLI rate-limit flags override that field.
+
 ## Edit and publish a revision
 
 ```bash

package/skills/xapi/guides/ws_gateway.md

@@ -1,6 +1,6 @@
 # WebSocket Gateway Guide
 
-Use xAPI's WebSocket Gateway for full-duplex, low-latency sessions such as OpenAI Realtime, streaming speech recognition, bidirectional text-to-speech, simultaneous interpretation, and podcast generation.
+Use xAPI's WebSocket Gateway for full-duplex, low-latency sessions such as GPT Live, OpenAI Realtime, streaming speech recognition, bidirectional text-to-speech, simultaneous interpretation, and podcast generation.
 
 The WebSocket Gateway shares the public `ai.xapi.to` host with the HTTP AI Gateway, but it is a separate protocol surface. An HTTP request continues to use the AI Gateway; a valid WebSocket Upgrade request is routed to the WebSocket Gateway.
 
@@ -9,6 +9,7 @@ The WebSocket Gateway shares the public `ai.xapi.to` host with the HTTP AI Gatew
 - [Choose the right interface](#choose-the-right-interface)
 - [Public URLs and routing](#public-urls-and-routing)
 - [Authentication](#authentication)
+- [GPT Live example](#gpt-live-example)
 - [OpenAI Realtime example](#openai-realtime-example)
 - [Browser connections](#browser-connections)
 - [Native protocol endpoints](#native-protocol-endpoints)
@@ -39,6 +40,7 @@ Current curated production paths include:
 
 | Path | Protocol | Typical use |
 |---|---|---|
+| `/v1/live/sessions` on the GPT Live service host | OpenAI Live Sessions JSON events | GPT-Live 1 voice with Client or managed Responses delegation |
 | `/v1/realtime` | OpenAI Realtime GA JSON events | Realtime text and voice |
 | `/v1/asr` | Volcengine ASR binary frames | Streaming speech recognition |
 | `/v1/tts` | Doubao bidirectional TTS binary frames | Streaming text-to-speech |
@@ -57,6 +59,15 @@ wss://<service-slug>.p.xapi.to/<endpoint-path>
 
 This avoids shared-path ambiguity and is required when the desired service uses a provider-native protocol that is not selected by the unified path. Console Try-It and review workflows can also address an endpoint exactly with `?endpoint=<endpoint-id>`.
 
+GPT Live currently uses the service-specific URL:
+
+```text
+wss://openai-live.p.xapi.to/v1/live/sessions
+```
+
+Do not replace it with `/v1/realtime`. Live Sessions uses `session.start` and
+`session.started`; Realtime uses a different session lifecycle and event model.
+
 ## Authentication
 
 Use the same xAPI key as the CLI and HTTP Gateway. Server-side clients should send one of these handshake headers:
@@ -78,6 +89,43 @@ The Gateway also accepts `?token=<XAPI_KEY>` or `?xapi-key=<XAPI_KEY>` for clien
 
 Authentication is checked before the WebSocket upgrade. Invalid handshakes therefore return an HTTP status instead of opening and immediately closing a socket.
 
+## GPT Live example
+
+GPT Live is a provider-native JSON event protocol, not an Action `call` and not
+OpenAI Realtime. The first client frame must be `session.start`. The production
+endpoint locks the Live model to `gpt-live-1`, disables storage, and lets the
+caller choose `client` or `responses` delegation once per connection. In
+`responses` mode, the managed Responses model and its limits remain
+server-controlled.
+
+The packaged `examples/openai-gpt-live-text.mjs` demonstrates the smallest
+managed-Responses lifecycle: connect with a server-side xAPI key, send
+`session.start`, wait for `session.started`, create a text item, request a
+response, and finish with `session.close` after the nested response completes.
+It intentionally omits microphone capture so the protocol boundary is clear.
+
+```bash
+# Install the example's WebSocket transport in your application directory.
+npm install ws
+
+# Supply XAPI_KEY through the process environment; never put it in source code
+# or pass it as a command-line argument.
+node examples/openai-gpt-live-text.mjs "Answer in one short sentence."
+```
+
+Voice clients use the same session lifecycle, then send base64 PCM chunks as
+`session.input_audio.append` events and consume `session.output_audio.delta`.
+Audio format, voice, interruption behavior, and the complete event schema must
+follow the current Live Sessions contract. Do not copy Realtime
+`conversation.item.create` or `input_audio_buffer.*` events into a Live session.
+
+With `client` delegation, the application must handle
+`session.delegation.created`, run its own text-model request, and return the
+result with `session.commentary.append`, then wait for
+`session.commentary.appended`. Selecting `client` does not make xAPI run a
+model on the application's behalf. Use `responses` when the managed backend is
+desired.
+
 ## OpenAI Realtime example
 
 The unified `/v1/realtime` route speaks the OpenAI Realtime GA JSON event protocol. It is native passthrough: send the same events you would send to the upstream Realtime API, but authenticate with the xAPI key.
@@ -121,15 +169,26 @@ Do not send the retired `OpenAI-Beta: realtime=v1` header. Session settings, aud
 The browser `WebSocket` API cannot set arbitrary handshake headers. The Gateway accepts an xAPI key or temporary token through a subprotocol entry:
 
 ```javascript
-const temporaryToken = await getTemporaryTokenFromYourBackend();
+const credential = await getEndpointBoundCredentialFromYourBackend(endpointId);
+if (Date.now() >= new Date(credential.latestStartAt).getTime()) {
+  throw new Error("refresh the credential before opening a full new session");
+}
 const ws = new WebSocket(
-  "wss://ai.xapi.to/v1/realtime",
-  [`xapi-key.${temporaryToken}`],
+  "wss://openai-live.p.xapi.to/v1/live/sessions",
+  ["xapi-ws-v1", `xapi-key.${credential.token}`],
 );
 ```
 
 Never embed a long-lived xAPI key in frontend JavaScript. Use the authenticated xAPI Console Try-It flow or your backend to obtain a short-lived token, then pass only that token to the browser. The Console's `POST /api/keys/ws-token` flow mints a temporary token for a WebSocket endpoint; it requires a logged-in entity account and an endpoint ID, and is not authenticated with a normal xAPI key.
 
+The credential is endpoint-bound and returns `expiresAt`, `latestStartAt`, and
+`maxDurationSec`. It may be reused for reconnects only while the new connection
+starts before `latestStartAt`; after that boundary, mint a fresh credential so
+the full advertised session and final `session.close` exchange fit inside its
+lifetime. If an endpoint declares public subprotocols, retain them and append
+the `xapi-key.*` entry; otherwise use the non-secret `xapi-ws-v1` marker shown
+above. Never log the secret subprotocol value.
+
 If a browser integration must use `?token=`, use only a short-lived token and avoid logging the complete URL.
 
 ## Native protocol endpoints
@@ -138,6 +197,7 @@ The Gateway forwards frames without translating the application protocol. The se
 
 | Adapter | Client frames | Important client requirement |
 |---|---|---|
+| `openai-live` | UTF-8 JSON text | First frame is `session.start`; choose Client or managed Responses delegation once. |
 | `openai-realtime` | UTF-8 JSON text | Use OpenAI Realtime GA events. |
 | `volcengine-asr` | Binary | Send the Volcengine ASR header/config/audio frame sequence; PCM configuration must match the audio bytes. |
 | `doubao-realtime` | Binary | Use the Doubao end-to-end realtime dialogue protocol through its service host or exact endpoint. |