From eb5d0f733b882d66553f2b18d5de66e936fae3a7 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 1/3] docs(agent-sdk): add Trust Wallet Agent SDK documentation --- README.md | 1 + 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, 513 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 1698b81..781275e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ Welcome to the Trust Wallet developer documentation. Here you can find documentation on contributing to Trust Wallet as well as on using Trust Wallet libraries on your own projects. +- [Trust Wallet Agent SDK](agent-sdk/agent-sdk.md) - [Developing for Trust Wallet platform](develop-for-trust/develop-for-trust.md) - [Browser Extension](develop-for-trust/browser-extension/browser-extension.md) - [Mobile (WalletConnect)](develop-for-trust/mobile/mobile.md) diff --git a/SUMMARY.md b/SUMMARY.md index 8834e46..467685b 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) - [Developing for Trust Wallet platform](develop-for-trust/develop-for-trust.md) - [Browser Extension](develop-for-trust/browser-extension/browser-extension.md) - [Ethereum & EVM chains](develop-for-trust/browser-extension/evm.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 7c44e0f6a7de3a66d1e1015575e98523f9d4b379 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 2/3] 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 3ece24db03e7e34f7e9f29ea3619121c3128e373 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 3/3] 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] ``` ---