From 907225cf05440fddaa7fdd7dc04f11ce91cb8c40 Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Feb 2026 16:52:11 +0800 Subject: [PATCH 01/11] docs(agent-sdk): add Trust Wallet Agent SDK documentation --- README.md | 11 ++ SUMMARY.md | 4 + agent-sdk/agent-sdk.md | 21 +++ agent-sdk/authentication.md | 67 ++++++++ agent-sdk/cli-reference.md | 318 ++++++++++++++++++++++++++++++++++++ agent-sdk/quickstart.md | 102 ++++++++++++ 6 files changed, 523 insertions(+) create mode 100644 agent-sdk/agent-sdk.md create mode 100644 agent-sdk/authentication.md create mode 100644 agent-sdk/cli-reference.md create mode 100644 agent-sdk/quickstart.md diff --git a/README.md b/README.md index 0a58917..766f86e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,17 @@ This documentation covers everything for developers: building on top of Trust Wa --- +## Trust Wallet Agent SDK + +### [Agent SDK](agent-sdk/agent-sdk.md) +Programmatic access to Trust Wallet's multichain infrastructure — balance queries, token prices, swaps, transaction history, and more — through a CLI and an MCP server for AI agents. + +- [Quickstart](agent-sdk/quickstart.md) +- [CLI Reference](agent-sdk/cli-reference.md) +- [Authentication](agent-sdk/authentication.md) + +--- + ## Build on Trust Wallet ### [Developing for Trust Wallet](develop-for-trust/develop-for-trust.md) diff --git a/SUMMARY.md b/SUMMARY.md index e004654..a7b922f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,6 +1,10 @@ # Table of contents - [Get Started](README.md) +- [Trust Wallet Agent SDK](agent-sdk/agent-sdk.md) + - [Quickstart](agent-sdk/quickstart.md) + - [CLI Reference](agent-sdk/cli-reference.md) + - [Authentication](agent-sdk/authentication.md) - [MCP Server](mcp/mcp.md) - [Agent Skills](claude-code-skills/claude-code-skills.md) - [Developing for Trust Wallet platform](develop-for-trust/develop-for-trust.md) diff --git a/agent-sdk/agent-sdk.md b/agent-sdk/agent-sdk.md new file mode 100644 index 0000000..9abae65 --- /dev/null +++ b/agent-sdk/agent-sdk.md @@ -0,0 +1,21 @@ +# Trust Wallet Agent SDK + +The Trust Wallet Agent SDK gives developers programmatic access to Trust Wallet's multichain infrastructure — balance queries, token prices, swaps, transaction history, and more — through a CLI, a TypeScript SDK, and an MCP server for AI agents. + +## What's included + +| Package | Description | +|---------|-------------| +| `@twak/cli` | Command-line interface — `twak` / `tw-agent` binaries | +| `@twak/sdk` | TypeScript SDK for server-side and agent integrations | +| MCP server | `twak serve` — connect any MCP-compatible AI agent | + +## Get started + +- [Quickstart](quickstart.md) — install the CLI and make your first request in 5 minutes +- [CLI Reference](cli-reference.md) — all commands, subcommands, and flags +- [Authentication](authentication.md) — API keys and HMAC signing + +## Developer portal + +Create and manage your API keys at [developer.trustwallet.com](https://developer.trustwallet.com). diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md new file mode 100644 index 0000000..297b15a --- /dev/null +++ b/agent-sdk/authentication.md @@ -0,0 +1,67 @@ +# Authentication + +All requests to the Trust Wallet API are authenticated with an **API access ID** and an **HMAC-SHA256 signature** derived from your HMAC secret. + +## Getting credentials + +1. Sign in at [developer.trustwallet.com](https://developer.trustwallet.com) +2. Create an app, then create an API key inside it +3. Copy your **Access ID** (`twk_live_...`) and **HMAC Secret** — the secret is shown only once + +## Configuring the CLI + +```bash +twak init --api-key twk_live_your_access_id \ + --api-secret your_hmac_secret +``` + +Or via environment variables: + +```bash +export TWAK_ACCESS_ID=twk_live_your_access_id +export TWAK_HMAC_SECRET=your_hmac_secret +``` + +## How HMAC signing works + +Every API request is signed with HMAC-SHA256 over four fields joined by newlines: + +``` +METHOD\nPATH\nNONCE\nBODY +``` + +| Field | Description | +|-------|-------------| +| `METHOD` | HTTP method in uppercase — `GET`, `POST`, `DELETE` | +| `PATH` | URL path without query string — `/v1/wallet/balance` | +| `NONCE` | Unix timestamp in milliseconds — prevents replay attacks | +| `BODY` | JSON-encoded request body, or empty string for GET | + +The resulting base64 signature is sent in the `X-TW-Signature` header alongside `X-TW-Access-Id` and `X-TW-Nonce`. + +The CLI and TypeScript SDK handle signing automatically — you only need to understand this if you are making raw HTTP calls. + +## Raw HTTP example + +```bash +NONCE=$(date +%s%3N) +METHOD="GET" +PATH="/v1/wallet/balance" +BODY="" +SIGNATURE=$(echo -n "$METHOD\n$PATH\n$NONCE\n$BODY" \ + | openssl dgst -sha256 -hmac "$TWAK_HMAC_SECRET" -binary \ + | base64) + +curl -X GET "https://api.trustwallet.com/v1/wallet/balance?\ + address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum" \ + -H "X-TW-Access-Id: $TWAK_ACCESS_ID" \ + -H "X-TW-Nonce: $NONCE" \ + -H "X-TW-Signature: $SIGNATURE" +``` + +## Security best practices + +- Never commit your HMAC secret to version control +- Add `.env` to `.gitignore` +- Rotate keys regularly from the developer portal +- Use separate keys for development and production diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md new file mode 100644 index 0000000..d132f04 --- /dev/null +++ b/agent-sdk/cli-reference.md @@ -0,0 +1,318 @@ +# CLI Reference + +The `twak` CLI (also aliased as `tw-agent`) provides full access to the Trust Wallet Agent SDK from the command line. + +**Install:** `npm install -g @twak/cli` + +--- + +## init + +Initialize configuration and save credentials. + +```bash +twak init --api-key --api-secret [--wc-project-id ] +``` + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | Yes | TWAK API access ID | +| `--api-secret` | Yes | HMAC secret | +| `--wc-project-id` | No | WalletConnect project ID | + +Credentials are saved to `~/.tw-agent/credentials.json`. + +--- + +## auth + +### auth setup + +```bash +twak auth setup --api-key --api-secret +``` + +### auth status + +```bash +twak auth status [--json] +``` + +--- + +## wallet + +### wallet create + +```bash +twak wallet create --password [--json] +``` + +### wallet address + +```bash +twak wallet address --chain --password [--json] +``` + +### wallet addresses + +```bash +twak wallet addresses --password [--json] +``` + +### wallet balance + +```bash +twak wallet balance --chain --password [--json] +``` + +### wallet export + +```bash +twak wallet export --password +``` + +### wallet connect + +Connect an external wallet via WalletConnect. + +```bash +twak wallet connect [--json] +``` + +### wallet status + +```bash +twak wallet status [--json] +``` + +--- + +## transfer + +```bash +twak transfer --to
--amount --token --password [--json] +``` + +--- + +## swap + +```bash +twak swap [--chain ] [--to-chain ] \ + [--slippage ] [--quote-only] [--password ] [--json] +``` + +Use `--quote-only` to preview without executing. + +--- + +## price + +```bash +twak price [--chain ] [--json] +``` + +Default chain is `ethereum`. + +--- + +## balance + +Get the native balance for any address using a SLIP44 coin ID. + +```bash +twak balance --address
--coin [--json] +``` + +Common coin IDs: `60` (Ethereum), `0` (Bitcoin), `501` (Solana). + +--- + +## holdings + +```bash +twak holdings --address
--coin [--json] +``` + +--- + +## search + +```bash +twak search [--networks ] [--limit ] [--json] +``` + +--- + +## trending + +```bash +twak trending [--limit ] [--json] +``` + +--- + +## history + +```bash +twak history --address
[--chain ] [--from ] \ + [--to ] [--limit ] [--json] +``` + +--- + +## tx + +```bash +twak tx --chain [--json] +``` + +--- + +## chains + +```bash +twak chains [--json] +``` + +--- + +## asset + +```bash +twak asset [--json] +``` + +--- + +## validate + +```bash +twak validate --address
[--asset-id ] [--json] +``` + +--- + +## risk + +Check token security and rug-risk info. + +```bash +twak risk [--json] +``` + +--- + +## erc20 + +### erc20 approve + +```bash +twak erc20 approve --token
--spender
--amount \ + --password [--json] +``` + +### erc20 allowance + +```bash +twak erc20 allowance --token
--owner
--spender
[--json] +``` + +--- + +## alert + +### alert create + +```bash +twak alert create --token --chain (--above | --below ) [--json] +``` + +### alert list + +```bash +twak alert list [--active] [--json] +``` + +### alert check + +```bash +twak alert check [--json] +``` + +### alert delete + +```bash +twak alert delete [--json] +``` + +--- + +## onramp + +### onramp quote + +```bash +twak onramp quote --amount --asset --wallet
\ + [--currency ] [--json] +``` + +### onramp buy + +```bash +twak onramp buy --quote-id --wallet
[--json] +``` + +### onramp sell-quote + +```bash +twak onramp sell-quote --amount --asset --wallet
\ + [--currency ] [--method ] [--json] +``` + +### onramp sell + +```bash +twak onramp sell --quote-id --wallet
[--json] +``` + +--- + +## automate + +### automate add + +Create a DCA or limit order automation. + +```bash +twak automate add --from --to --amount \ + [--chain ] [--interval ] \ + [--price ] [--condition above|below] [--json] +``` + +### automate list + +```bash +twak automate list [--all] [--json] +``` + +### automate delete + +```bash +twak automate delete [--json] +``` + +--- + +## serve + +Start an MCP server (stdio) or REST API server for AI agent integrations. + +```bash +twak serve [--rest] [--port ] [--x402] \ + [--payment-amount ] [--payment-asset ] \ + [--payment-chain ] [--payment-recipient
] +``` + +Use `--rest` to start an HTTP server instead of stdio MCP. diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md new file mode 100644 index 0000000..1708a0d --- /dev/null +++ b/agent-sdk/quickstart.md @@ -0,0 +1,102 @@ +# Quickstart + +Get from zero to your first API call in under 5 minutes using the `twak` CLI. + +## Step 1 — Install the CLI + +```bash +npm install -g @twak/cli +``` + +Verify the install: + +```bash +twak --version +``` + +The CLI exposes two aliases: `twak` and `tw-agent`. + +## Step 2 — Configure credentials + +Get your API key and HMAC secret from the [developer portal](https://developer.trustwallet.com/dashboard/keys), then run: + +```bash +twak init --api-key twk_live_your_access_id \ + --api-secret your_hmac_secret +``` + +Credentials are stored in `~/.tw-agent/credentials.json`. + +Alternatively, export environment variables (useful in CI/CD): + +```bash +export TWAK_ACCESS_ID=twk_live_your_access_id +export TWAK_HMAC_SECRET=your_hmac_secret +``` + +Confirm the setup: + +```bash +twak auth status +``` + +> **Never commit your HMAC secret to version control.** If using a `.env` file, add it to `.gitignore`. + +## Step 3 — Make your first request + +Fetch the current ETH price — no wallet required: + +```bash +twak price ETH +``` + +Add `--json` for machine-readable output: + +```bash +twak price ETH --json +# {"token":"ETH","chain":"ethereum","priceUsd":3241.87} +``` + +List all supported chains: + +```bash +twak chains +``` + +## Step 4 — Explore more commands + +```bash +# ETH balance for any address (coin 60 = Ethereum) +twak balance --address --coin 60 + +# All token holdings for an address +twak holdings --address --coin 60 + +# Top 5 trending tokens right now +twak trending --limit 5 + +# Search for tokens by name or symbol +twak search uniswap + +# Transaction history for an address +twak history --address --chain ethereum + +# Security / rug-risk check for a token +twak risk c60_t0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 + +# Create an embedded agent wallet +twak wallet create --password + +# Execute a token swap +twak swap 0.1 ETH USDC --chain ethereum + +# Start an MCP server for AI agent integrations +twak serve +``` + +Run any command with `--help` to see all options. + +## Next steps + +- [CLI Reference](cli-reference.md) — full command reference +- [Authentication](authentication.md) — how HMAC signing works From fe2fe3e6f1c0d573f823f680d5d5d46428c41dfa Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Feb 2026 17:18:55 +0800 Subject: [PATCH 02/11] fix(agent-sdk): correct portal URL to portal.trustwallet.com MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit developer.trustwallet.com was incorrect — the actual portal is at portal.trustwallet.com. Also fixes /dashboard/keys to /dashboard/apps. --- agent-sdk/agent-sdk.md | 2 +- agent-sdk/authentication.md | 39 ++++++++++++++++++++++++------------- agent-sdk/quickstart.md | 2 +- 3 files changed, 27 insertions(+), 16 deletions(-) diff --git a/agent-sdk/agent-sdk.md b/agent-sdk/agent-sdk.md index 9abae65..3a79c95 100644 --- a/agent-sdk/agent-sdk.md +++ b/agent-sdk/agent-sdk.md @@ -18,4 +18,4 @@ The Trust Wallet Agent SDK gives developers programmatic access to Trust Wallet' ## Developer portal -Create and manage your API keys at [developer.trustwallet.com](https://developer.trustwallet.com). +Create and manage your API keys at [portal.trustwallet.com](https://portal.trustwallet.com). diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md index 297b15a..d237ecb 100644 --- a/agent-sdk/authentication.md +++ b/agent-sdk/authentication.md @@ -4,7 +4,7 @@ All requests to the Trust Wallet API are authenticated with an **API access ID** ## Getting credentials -1. Sign in at [developer.trustwallet.com](https://developer.trustwallet.com) +1. Sign in at [portal.trustwallet.com](https://portal.trustwallet.com) 2. Create an app, then create an API key inside it 3. Copy your **Access ID** (`twk_live_...`) and **HMAC Secret** — the secret is shown only once @@ -24,39 +24,50 @@ export TWAK_HMAC_SECRET=your_hmac_secret ## How HMAC signing works -Every API request is signed with HMAC-SHA256 over four fields joined by newlines: +Every API request is signed with HMAC-SHA256 over six fields concatenated together: ``` -METHOD\nPATH\nNONCE\nBODY +METHOD + PATH + QUERY + ACCESS_ID + NONCE + DATE ``` | Field | Description | |-------|-------------| | `METHOD` | HTTP method in uppercase — `GET`, `POST`, `DELETE` | | `PATH` | URL path without query string — `/v1/wallet/balance` | -| `NONCE` | Unix timestamp in milliseconds — prevents replay attacks | -| `BODY` | JSON-encoded request body, or empty string for GET | +| `QUERY` | Query string (without leading `?`), or empty string | +| `ACCESS_ID` | Your API access ID | +| `NONCE` | Unique random string — prevents replay attacks | +| `DATE` | ISO 8601 timestamp — validated within a ±5 min window | -The resulting base64 signature is sent in the `X-TW-Signature` header alongside `X-TW-Access-Id` and `X-TW-Nonce`. +The resulting base64 signature is sent in the `Authorization` header. Three additional headers identify the request: + +| Header | Value | +|--------|-------| +| `X-TW-Credential` | Your API access ID | +| `X-TW-Nonce` | The nonce used in signing | +| `X-TW-Date` | The timestamp used in signing | +| `Authorization` | Base64-encoded HMAC-SHA256 signature | The CLI and TypeScript SDK handle signing automatically — you only need to understand this if you are making raw HTTP calls. ## Raw HTTP example ```bash -NONCE=$(date +%s%3N) +ACCESS_ID="$TWAK_ACCESS_ID" +NONCE=$(uuidgen | tr -d '-') +DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") METHOD="GET" -PATH="/v1/wallet/balance" -BODY="" -SIGNATURE=$(echo -n "$METHOD\n$PATH\n$NONCE\n$BODY" \ +REQ_PATH="/v1/wallet/balance" +QUERY="address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum" +SIGNATURE=$(printf '%s' "${METHOD}${REQ_PATH}${QUERY}${ACCESS_ID}${NONCE}${DATE}" \ | openssl dgst -sha256 -hmac "$TWAK_HMAC_SECRET" -binary \ | base64) -curl -X GET "https://api.trustwallet.com/v1/wallet/balance?\ - address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum" \ - -H "X-TW-Access-Id: $TWAK_ACCESS_ID" \ +curl -X GET "https://api.trustwallet.com${REQ_PATH}?${QUERY}" \ + -H "X-TW-Credential: $ACCESS_ID" \ -H "X-TW-Nonce: $NONCE" \ - -H "X-TW-Signature: $SIGNATURE" + -H "X-TW-Date: $DATE" \ + -H "Authorization: $SIGNATURE" ``` ## Security best practices diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md index 1708a0d..2d8efff 100644 --- a/agent-sdk/quickstart.md +++ b/agent-sdk/quickstart.md @@ -18,7 +18,7 @@ The CLI exposes two aliases: `twak` and `tw-agent`. ## Step 2 — Configure credentials -Get your API key and HMAC secret from the [developer portal](https://developer.trustwallet.com/dashboard/keys), then run: +Get your API key and HMAC secret from the [developer portal](https://portal.trustwallet.com/dashboard/apps), then run: ```bash twak init --api-key twk_live_your_access_id \ From 99c5d1835f923ad74d8fed56b6b4d57191e90e16 Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Feb 2026 17:19:03 +0800 Subject: [PATCH 03/11] fix(agent-sdk): correct CLI reference against actual source - Add missing wallet keychain subcommands (save/delete/check) - Add missing --no-keychain flag to wallet create - Mark --password optional where it falls back to keychain/env var - Add --wc-project-id to auth setup - Fix erc20 --token to use assetId format instead of address --- agent-sdk/cli-reference.md | 40 ++++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md index d132f04..9be540b 100644 --- a/agent-sdk/cli-reference.md +++ b/agent-sdk/cli-reference.md @@ -29,7 +29,7 @@ Credentials are saved to `~/.tw-agent/credentials.json`. ### auth setup ```bash -twak auth setup --api-key --api-secret +twak auth setup --api-key --api-secret [--wc-project-id ] ``` ### auth status @@ -45,31 +45,53 @@ twak auth status [--json] ### wallet create ```bash -twak wallet create --password [--json] +twak wallet create --password [--no-keychain] [--json] ``` ### wallet address ```bash -twak wallet address --chain --password [--json] +twak wallet address --chain [--password ] [--json] ``` +Password falls back to the OS keychain or `TWAK_WALLET_PASSWORD` environment variable. + ### wallet addresses ```bash -twak wallet addresses --password [--json] +twak wallet addresses [--password ] [--json] ``` ### wallet balance ```bash -twak wallet balance --chain --password [--json] +twak wallet balance --chain [--password ] [--json] ``` ### wallet export ```bash -twak wallet export --password +twak wallet export [--password ] +``` + +### wallet keychain save + +Save the wallet password to the OS keychain for passwordless usage. + +```bash +twak wallet keychain save --password +``` + +### wallet keychain delete + +```bash +twak wallet keychain delete +``` + +### wallet keychain check + +```bash +twak wallet keychain check ``` ### wallet connect @@ -209,14 +231,16 @@ twak risk [--json] ### erc20 approve ```bash -twak erc20 approve --token
--spender
--amount \ +twak erc20 approve --token --spender
--amount \ --password [--json] ``` +Token uses the Trust Wallet asset ID format (e.g., `c60_t0xA0b8...`). + ### erc20 allowance ```bash -twak erc20 allowance --token
--owner
--spender
[--json] +twak erc20 allowance --token --owner
--spender
[--json] ``` --- From c58fc53b81ce5e1d053f42e86cc8bfb675cd2d65 Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 02:36:27 +0700 Subject: [PATCH 04/11] docs: update agent SDK docs with current CLI state - Package name: @trustwallet/cli (not @twak/cli) - Remove tw-agent alias (no longer exists) - Config dir: ~/.twak/ (not ~/.tw-agent/) - Remove onramp, automate, walletconnect commands (disabled in public CLI) - Add missing commands: portfolio, sign-message, dapps, trending categories - Add transfer safety flags: --max-usd, --skip-safety-check, --confirm-to - Add erc20 revoke, swap slippage cap, serve --auto-lock - Fix API URL: tws.trustwallet.com (not api.trustwallet.com) --- agent-sdk/agent-sdk.md | 4 +- agent-sdk/authentication.md | 2 +- agent-sdk/cli-reference.md | 154 ++++++++++++++++++------------------ agent-sdk/quickstart.md | 21 +++-- 4 files changed, 94 insertions(+), 87 deletions(-) diff --git a/agent-sdk/agent-sdk.md b/agent-sdk/agent-sdk.md index 3a79c95..aea237a 100644 --- a/agent-sdk/agent-sdk.md +++ b/agent-sdk/agent-sdk.md @@ -6,8 +6,8 @@ The Trust Wallet Agent SDK gives developers programmatic access to Trust Wallet' | Package | Description | |---------|-------------| -| `@twak/cli` | Command-line interface — `twak` / `tw-agent` binaries | -| `@twak/sdk` | TypeScript SDK for server-side and agent integrations | +| `@trustwallet/cli` | Command-line interface — `twak` binary | +| `@twak/*` | TypeScript SDK packages for server-side and agent integrations | | MCP server | `twak serve` — connect any MCP-compatible AI agent | ## Get started diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md index d237ecb..1ceaae3 100644 --- a/agent-sdk/authentication.md +++ b/agent-sdk/authentication.md @@ -63,7 +63,7 @@ SIGNATURE=$(printf '%s' "${METHOD}${REQ_PATH}${QUERY}${ACCESS_ID}${NONCE}${DATE} | openssl dgst -sha256 -hmac "$TWAK_HMAC_SECRET" -binary \ | base64) -curl -X GET "https://api.trustwallet.com${REQ_PATH}?${QUERY}" \ +curl -X GET "https://tws.trustwallet.com${REQ_PATH}?${QUERY}" \ -H "X-TW-Credential: $ACCESS_ID" \ -H "X-TW-Nonce: $NONCE" \ -H "X-TW-Date: $DATE" \ diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md index 9be540b..6d00784 100644 --- a/agent-sdk/cli-reference.md +++ b/agent-sdk/cli-reference.md @@ -1,8 +1,8 @@ # CLI Reference -The `twak` CLI (also aliased as `tw-agent`) provides full access to the Trust Wallet Agent SDK from the command line. +The `twak` CLI provides full access to the Trust Wallet Agent SDK from the command line. -**Install:** `npm install -g @twak/cli` +**Install:** `npm install -g @trustwallet/cli` --- @@ -11,16 +11,15 @@ The `twak` CLI (also aliased as `tw-agent`) provides full access to the Trust Wa Initialize configuration and save credentials. ```bash -twak init --api-key --api-secret [--wc-project-id ] +twak init --api-key --api-secret ``` | Flag | Required | Description | |------|----------|-------------| | `--api-key` | Yes | TWAK API access ID | | `--api-secret` | Yes | HMAC secret | -| `--wc-project-id` | No | WalletConnect project ID | -Credentials are saved to `~/.tw-agent/credentials.json`. +Credentials are saved to `~/.twak/credentials.json`. --- @@ -29,7 +28,7 @@ Credentials are saved to `~/.tw-agent/credentials.json`. ### auth setup ```bash -twak auth setup --api-key --api-secret [--wc-project-id ] +twak auth setup --api-key --api-secret ``` ### auth status @@ -68,6 +67,24 @@ twak wallet addresses [--password ] [--json] twak wallet balance --chain [--password ] [--json] ``` +### wallet portfolio + +Full portfolio across all chains — native balances, token holdings, and USD values. + +```bash +twak wallet portfolio [--chains ] [--password ] [--json] +``` + +Default chains include all major EVM chains plus Solana and TRON. + +### wallet sign-message + +Sign an arbitrary message with the agent wallet key. + +```bash +twak wallet sign-message --chain --message [--password ] [--json] +``` + ### wallet export ```bash @@ -94,14 +111,6 @@ twak wallet keychain delete twak wallet keychain check ``` -### wallet connect - -Connect an external wallet via WalletConnect. - -```bash -twak wallet connect [--json] -``` - ### wallet status ```bash @@ -113,9 +122,19 @@ twak wallet status [--json] ## transfer ```bash -twak transfer --to
--amount --token --password [--json] +twak transfer --to
--amount --token \ + [--max-usd ] [--skip-safety-check] [--password ] [--json] ``` +| Flag | Description | +|------|-------------| +| `--to` | Destination address or ENS name (e.g., `vitalik.eth`) | +| `--amount` | Amount in human-readable format | +| `--token` | Asset ID (e.g., `c60` for ETH, `c60_t0xA0b8...` for ERC-20) | +| `--max-usd` | Maximum allowed transfer value in USD (default: 10000) | +| `--skip-safety-check` | Skip the USD-value safety check | +| `--confirm-to` | Pin expected resolved address — rejects if ENS resolves differently | + --- ## swap @@ -125,6 +144,13 @@ twak swap [--chain ] [--to-chain ] \ [--slippage ] [--quote-only] [--password ] [--json] ``` +| Flag | Description | +|------|-------------| +| `--chain` | Source chain (default: ethereum) | +| `--to-chain` | Destination chain for cross-chain swaps | +| `--slippage` | Slippage tolerance % (default: 1, max: 50) | +| `--quote-only` | Preview quote without executing | + Use `--quote-only` to preview without executing. --- @@ -135,7 +161,7 @@ Use `--quote-only` to preview without executing. twak price [--chain ] [--json] ``` -Default chain is `ethereum`. +Chain is auto-detected from native token symbols (ETH, BNB, SOL, etc.). --- @@ -170,9 +196,25 @@ twak search [--networks ] [--limit ] [--json] ## trending ```bash -twak trending [--limit ] [--json] +twak trending [--category ] [--sort ] [--limit ] [--json] ``` +Categories: `ai`, `rwa`, `memes`, `defi`, `dex`, `bnb`, `eth`, `sol`, `pumpfun`, `launchpad`, `layer1`. + +Sort fields: `price_change` (default), `market_cap`, `volume`. + +--- + +## dapps + +Browse featured DApps and protocols. + +```bash +twak dapps [--category ] [--json] +``` + +Categories: `defi`, `dex`, `lending`, `nft`, `gaming`, `social`. + --- ## history @@ -232,11 +274,17 @@ twak risk [--json] ```bash twak erc20 approve --token --spender
--amount \ - --password [--json] + [--confirm-unlimited] --password [--json] ``` Token uses the Trust Wallet asset ID format (e.g., `c60_t0xA0b8...`). +### erc20 revoke + +```bash +twak erc20 revoke --token --spender
--password [--json] +``` + ### erc20 allowance ```bash @@ -273,70 +321,22 @@ twak alert delete [--json] --- -## onramp - -### onramp quote - -```bash -twak onramp quote --amount --asset --wallet
\ - [--currency ] [--json] -``` - -### onramp buy - -```bash -twak onramp buy --quote-id --wallet
[--json] -``` - -### onramp sell-quote - -```bash -twak onramp sell-quote --amount --asset --wallet
\ - [--currency ] [--method ] [--json] -``` - -### onramp sell - -```bash -twak onramp sell --quote-id --wallet
[--json] -``` - ---- - -## automate - -### automate add - -Create a DCA or limit order automation. - -```bash -twak automate add --from --to --amount \ - [--chain ] [--interval ] \ - [--price ] [--condition above|below] [--json] -``` - -### automate list - -```bash -twak automate list [--all] [--json] -``` - -### automate delete - -```bash -twak automate delete [--json] -``` - ---- - ## serve Start an MCP server (stdio) or REST API server for AI agent integrations. ```bash -twak serve [--rest] [--port ] [--x402] \ - [--payment-amount ] [--payment-asset ] \ +twak serve [--rest] [--port ] [--host ] \ + [--auto-lock ] [--password ] \ + [--x402] [--payment-amount ] [--payment-asset ] \ [--payment-chain ] [--payment-recipient
] ``` -Use `--rest` to start an HTTP server instead of stdio MCP. +| Flag | Description | +|------|-------------| +| `--rest` | Start REST HTTP server instead of MCP stdio | +| `--port` | Port for REST server (default: 3000) | +| `--auto-lock` | Auto-lock wallet after N minutes of inactivity | +| `--x402` | Require x402 micropayment for REST endpoints | + +The REST server requires Bearer token authentication using your HMAC secret. diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md index 2d8efff..bd19af7 100644 --- a/agent-sdk/quickstart.md +++ b/agent-sdk/quickstart.md @@ -5,7 +5,7 @@ Get from zero to your first API call in under 5 minutes using the `twak` CLI. ## Step 1 — Install the CLI ```bash -npm install -g @twak/cli +npm install -g @trustwallet/cli ``` Verify the install: @@ -14,8 +14,6 @@ Verify the install: twak --version ``` -The CLI exposes two aliases: `twak` and `tw-agent`. - ## Step 2 — Configure credentials Get your API key and HMAC secret from the [developer portal](https://portal.trustwallet.com/dashboard/apps), then run: @@ -25,7 +23,7 @@ twak init --api-key twk_live_your_access_id \ --api-secret your_hmac_secret ``` -Credentials are stored in `~/.tw-agent/credentials.json`. +Credentials are stored in `~/.twak/credentials.json`. Alternatively, export environment variables (useful in CI/CD): @@ -54,7 +52,6 @@ Add `--json` for machine-readable output: ```bash twak price ETH --json -# {"token":"ETH","chain":"ethereum","priceUsd":3241.87} ``` List all supported chains: @@ -72,8 +69,14 @@ twak balance --address --coin 60 # All token holdings for an address twak holdings --address --coin 60 -# Top 5 trending tokens right now +# Trending tokens (with optional category and sort) twak trending --limit 5 +twak trending --category ai +twak trending --category memes --sort volume + +# Browse DApps and protocols +twak dapps +twak dapps --category defi # Search for tokens by name or symbol twak search uniswap @@ -87,7 +90,11 @@ twak risk c60_t0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 # Create an embedded agent wallet twak wallet create --password -# Execute a token swap +# Portfolio with USD values across all chains +twak wallet portfolio + +# Get a swap quote first, then execute +twak swap 0.1 ETH USDC --chain ethereum --quote-only twak swap 0.1 ETH USDC --chain ethereum # Start an MCP server for AI agent integrations From 57f083309ad7c6882033d7df4dba5cd01d3fea9d Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 02:38:12 +0700 Subject: [PATCH 05/11] =?UTF-8?q?docs:=20simplify=20overview=20=E2=80=94?= =?UTF-8?q?=20CLI=20only=20for=20now?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent-sdk/agent-sdk.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/agent-sdk/agent-sdk.md b/agent-sdk/agent-sdk.md index aea237a..3fac85d 100644 --- a/agent-sdk/agent-sdk.md +++ b/agent-sdk/agent-sdk.md @@ -1,14 +1,12 @@ # Trust Wallet Agent SDK -The Trust Wallet Agent SDK gives developers programmatic access to Trust Wallet's multichain infrastructure — balance queries, token prices, swaps, transaction history, and more — through a CLI, a TypeScript SDK, and an MCP server for AI agents. +The Trust Wallet Agent SDK gives developers programmatic access to Trust Wallet's multichain infrastructure — balance queries, token prices, swaps, transaction history, and more — through a CLI and an MCP server for AI agents. -## What's included +## Install -| Package | Description | -|---------|-------------| -| `@trustwallet/cli` | Command-line interface — `twak` binary | -| `@twak/*` | TypeScript SDK packages for server-side and agent integrations | -| MCP server | `twak serve` — connect any MCP-compatible AI agent | +```bash +npm install -g @trustwallet/cli +``` ## Get started From 36748b84e8d37e6d47be118a4377460a77fde3ff Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 02:41:52 +0700 Subject: [PATCH 06/11] fix: correct access ID format, API path, and remove wallet export - Access IDs are plain hex, not twk_live_ prefixed - Use real API path /v1/search/assets in auth example - Remove wallet export (not a registered CLI command) --- agent-sdk/authentication.md | 10 +++++----- agent-sdk/cli-reference.md | 6 ------ agent-sdk/quickstart.md | 4 ++-- 3 files changed, 7 insertions(+), 13 deletions(-) diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md index 1ceaae3..f1e10e5 100644 --- a/agent-sdk/authentication.md +++ b/agent-sdk/authentication.md @@ -6,19 +6,19 @@ All requests to the Trust Wallet API are authenticated with an **API access ID** 1. Sign in at [portal.trustwallet.com](https://portal.trustwallet.com) 2. Create an app, then create an API key inside it -3. Copy your **Access ID** (`twk_live_...`) and **HMAC Secret** — the secret is shown only once +3. Copy your **Access ID** and **HMAC Secret** — the secret is shown only once ## Configuring the CLI ```bash -twak init --api-key twk_live_your_access_id \ +twak init --api-key your_access_id \ --api-secret your_hmac_secret ``` Or via environment variables: ```bash -export TWAK_ACCESS_ID=twk_live_your_access_id +export TWAK_ACCESS_ID=your_access_id export TWAK_HMAC_SECRET=your_hmac_secret ``` @@ -57,8 +57,8 @@ ACCESS_ID="$TWAK_ACCESS_ID" NONCE=$(uuidgen | tr -d '-') DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") METHOD="GET" -REQ_PATH="/v1/wallet/balance" -QUERY="address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum" +REQ_PATH="/v1/search/assets" +QUERY="query=ethereum&limit=5" SIGNATURE=$(printf '%s' "${METHOD}${REQ_PATH}${QUERY}${ACCESS_ID}${NONCE}${DATE}" \ | openssl dgst -sha256 -hmac "$TWAK_HMAC_SECRET" -binary \ | base64) diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md index 6d00784..dd618aa 100644 --- a/agent-sdk/cli-reference.md +++ b/agent-sdk/cli-reference.md @@ -85,12 +85,6 @@ Sign an arbitrary message with the agent wallet key. twak wallet sign-message --chain --message [--password ] [--json] ``` -### wallet export - -```bash -twak wallet export [--password ] -``` - ### wallet keychain save Save the wallet password to the OS keychain for passwordless usage. diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md index bd19af7..557c1e5 100644 --- a/agent-sdk/quickstart.md +++ b/agent-sdk/quickstart.md @@ -19,7 +19,7 @@ twak --version Get your API key and HMAC secret from the [developer portal](https://portal.trustwallet.com/dashboard/apps), then run: ```bash -twak init --api-key twk_live_your_access_id \ +twak init --api-key your_access_id \ --api-secret your_hmac_secret ``` @@ -28,7 +28,7 @@ Credentials are stored in `~/.twak/credentials.json`. Alternatively, export environment variables (useful in CI/CD): ```bash -export TWAK_ACCESS_ID=twk_live_your_access_id +export TWAK_ACCESS_ID=your_access_id export TWAK_HMAC_SECRET=your_hmac_secret ``` From 571939691218058b723cb9c7443565af0078b98d Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 03:09:25 +0700 Subject: [PATCH 07/11] fix(agent-sdk): address copilot review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add --confirm-to to transfer command synopsis - Clarify REST server auth (Bearer token, not HMAC signing) - Fix "three headers" → "four headers" in auth docs --- agent-sdk/authentication.md | 2 +- agent-sdk/cli-reference.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md index f1e10e5..57700a6 100644 --- a/agent-sdk/authentication.md +++ b/agent-sdk/authentication.md @@ -39,7 +39,7 @@ METHOD + PATH + QUERY + ACCESS_ID + NONCE + DATE | `NONCE` | Unique random string — prevents replay attacks | | `DATE` | ISO 8601 timestamp — validated within a ±5 min window | -The resulting base64 signature is sent in the `Authorization` header. Three additional headers identify the request: +The resulting base64 signature is sent in the `Authorization` header. Four headers are required on every request: | Header | Value | |--------|-------| diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md index dd618aa..8061894 100644 --- a/agent-sdk/cli-reference.md +++ b/agent-sdk/cli-reference.md @@ -117,7 +117,8 @@ twak wallet status [--json] ```bash twak transfer --to
--amount --token \ - [--max-usd ] [--skip-safety-check] [--password ] [--json] + [--confirm-to
] [--max-usd ] [--skip-safety-check] \ + [--password ] [--json] ``` | Flag | Description | @@ -333,4 +334,4 @@ twak serve [--rest] [--port ] [--host ] \ | `--auto-lock` | Auto-lock wallet after N minutes of inactivity | | `--x402` | Require x402 micropayment for REST endpoints | -The REST server requires Bearer token authentication using your HMAC secret. +The REST server authenticates requests via `Authorization: Bearer `. This is separate from the HMAC signing used by `tws.trustwallet.com` — the REST server runs locally and uses the raw secret as a shared token for simplicity. From 82cb6859aef78126ae02b6b1cd86ab42619ff0da Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 13:37:59 +0700 Subject: [PATCH 08/11] docs(agent-sdk): clarify credential storage guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Recommend twak init for persistent local credentials (0600 permissions). Env vars are for CI/CD only — explicitly warn against adding secrets to shell config files. Add keychain and twak init to security best practices. --- agent-sdk/authentication.md | 12 +++++++++--- agent-sdk/quickstart.md | 6 ++++-- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md index 57700a6..d1cfad5 100644 --- a/agent-sdk/authentication.md +++ b/agent-sdk/authentication.md @@ -10,18 +10,22 @@ All requests to the Trust Wallet API are authenticated with an **API access ID** ## Configuring the CLI +The recommended approach is `twak init`, which stores credentials in `~/.twak/credentials.json` with `0600` permissions: + ```bash twak init --api-key your_access_id \ --api-secret your_hmac_secret ``` -Or via environment variables: +For CI/CD pipelines, use environment variables: ```bash export TWAK_ACCESS_ID=your_access_id export TWAK_HMAC_SECRET=your_hmac_secret ``` +> **Do not add these exports to shell config files** (`~/.zshrc`, `~/.bashrc`). Use `twak init` for persistent local credentials. Env vars are intended for ephemeral CI/CD environments where secrets are injected at runtime. + ## How HMAC signing works Every API request is signed with HMAC-SHA256 over six fields concatenated together: @@ -72,7 +76,9 @@ curl -X GET "https://tws.trustwallet.com${REQ_PATH}?${QUERY}" \ ## Security best practices -- Never commit your HMAC secret to version control -- Add `.env` to `.gitignore` +- Use `twak init` for local credentials — stores in `~/.twak/credentials.json` with restricted permissions +- Use `twak wallet keychain save` to store the wallet password in the OS keychain (macOS Keychain / Linux Secret Service) +- Never commit your HMAC secret to version control — add `.env` to `.gitignore` +- Never add credentials to shell config files (`~/.zshrc`, `~/.bashrc`) — use `twak init` instead - Rotate keys regularly from the developer portal - Use separate keys for development and production diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md index 557c1e5..c0e242c 100644 --- a/agent-sdk/quickstart.md +++ b/agent-sdk/quickstart.md @@ -23,15 +23,17 @@ twak init --api-key your_access_id \ --api-secret your_hmac_secret ``` -Credentials are stored in `~/.twak/credentials.json`. +Credentials are stored in `~/.twak/credentials.json` (file permissions `0600`). This is the recommended approach for local development. -Alternatively, export environment variables (useful in CI/CD): +For CI/CD pipelines, use environment variables instead: ```bash export TWAK_ACCESS_ID=your_access_id export TWAK_HMAC_SECRET=your_hmac_secret ``` +> **Do not add these exports to `~/.zshrc` or `~/.bashrc`.** Use `twak init` for persistent local credentials — it stores them in a dedicated file with restricted permissions. Env vars are intended for ephemeral CI/CD environments. + Confirm the setup: ```bash From 42cf13db9ff7ace46fcc2f29b8e7efd3ba1c4393 Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 13:39:07 +0700 Subject: [PATCH 09/11] docs(agent-sdk): add npx as primary install method and EACCES fix npx requires no global install and avoids the common EACCES permission error on macOS. Also suggest nvm as a permanent fix. --- agent-sdk/cli-reference.md | 2 +- agent-sdk/quickstart.md | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md index 8061894..d2ea430 100644 --- a/agent-sdk/cli-reference.md +++ b/agent-sdk/cli-reference.md @@ -2,7 +2,7 @@ The `twak` CLI provides full access to the Trust Wallet Agent SDK from the command line. -**Install:** `npm install -g @trustwallet/cli` +**Run:** `npx @trustwallet/cli ` or install globally with `npm install -g @trustwallet/cli` --- diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md index c0e242c..2e28e3b 100644 --- a/agent-sdk/quickstart.md +++ b/agent-sdk/quickstart.md @@ -4,16 +4,21 @@ Get from zero to your first API call in under 5 minutes using the `twak` CLI. ## Step 1 — Install the CLI +Run directly without installing (recommended): + ```bash -npm install -g @trustwallet/cli +npx @trustwallet/cli --version ``` -Verify the install: +Or install globally: ```bash +npm install -g @trustwallet/cli twak --version ``` +> **Permission denied?** If you get `EACCES` on macOS/Linux, either use `npx @trustwallet/cli` (no install needed), install Node via [nvm](https://github.com/nvm-sh/nvm) (avoids `/usr/local` permissions), or run `sudo npm install -g @trustwallet/cli`. + ## Step 2 — Configure credentials Get your API key and HMAC secret from the [developer portal](https://portal.trustwallet.com/dashboard/apps), then run: From 018f9b19650f6d49108587b1572876325930561c Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 13:51:57 +0700 Subject: [PATCH 10/11] fix(agent-sdk): fix CLI reference accuracy - Remove non-existent holdings command - Add --all and --no-tokens flags to wallet balance - Add missing trending categories (bonk, launchpool) - Add missing dapps flags (--search, --categories, --limit) --- agent-sdk/cli-reference.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/agent-sdk/cli-reference.md b/agent-sdk/cli-reference.md index d2ea430..6e10943 100644 --- a/agent-sdk/cli-reference.md +++ b/agent-sdk/cli-reference.md @@ -64,9 +64,11 @@ twak wallet addresses [--password ] [--json] ### wallet balance ```bash -twak wallet balance --chain [--password ] [--json] +twak wallet balance [--chain ] [--all] [--no-tokens] [--password ] [--json] ``` +Use `--all` to show balances across all chains with funds. Use `--no-tokens` to skip token balance lookup. + ### wallet portfolio Full portfolio across all chains — native balances, token holdings, and USD values. @@ -172,14 +174,6 @@ Common coin IDs: `60` (Ethereum), `0` (Bitcoin), `501` (Solana). --- -## holdings - -```bash -twak holdings --address
--coin [--json] -``` - ---- - ## search ```bash @@ -194,7 +188,7 @@ twak search [--networks ] [--limit ] [--json] twak trending [--category ] [--sort ] [--limit ] [--json] ``` -Categories: `ai`, `rwa`, `memes`, `defi`, `dex`, `bnb`, `eth`, `sol`, `pumpfun`, `launchpad`, `layer1`. +Categories: `ai`, `rwa`, `memes`, `defi`, `dex`, `bnb`, `eth`, `sol`, `pumpfun`, `bonk`, `launchpad`, `launchpool`, `layer1`. Sort fields: `price_change` (default), `market_cap`, `volume`. @@ -205,10 +199,10 @@ Sort fields: `price_change` (default), `market_cap`, `volume`. Browse featured DApps and protocols. ```bash -twak dapps [--category ] [--json] +twak dapps [--category ] [--search ] [--categories] [--limit ] [--json] ``` -Categories: `defi`, `dex`, `lending`, `nft`, `gaming`, `social`. +Categories: `defi`, `dex`, `lending`, `nft`, `gaming`, `social`. Use `--categories` to list all available. --- From 3e63c6616e9ddfaffaf281e0b74416e90e1af993 Mon Sep 17 00:00:00 2001 From: vcoolish-tw <251996827+vcoolish-tw@users.noreply.github.com> Date: Thu, 26 Mar 2026 13:53:43 +0700 Subject: [PATCH 11/11] fix(agent-sdk): use npx as primary install in overview --- agent-sdk/agent-sdk.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/agent-sdk/agent-sdk.md b/agent-sdk/agent-sdk.md index 3fac85d..bb5b761 100644 --- a/agent-sdk/agent-sdk.md +++ b/agent-sdk/agent-sdk.md @@ -5,9 +5,11 @@ The Trust Wallet Agent SDK gives developers programmatic access to Trust Wallet' ## Install ```bash -npm install -g @trustwallet/cli +npx @trustwallet/cli --version ``` +Or install globally: `npm install -g @trustwallet/cli` + ## Get started - [Quickstart](quickstart.md) — install the CLI and make your first request in 5 minutes