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..bb5b761 --- /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 and an MCP server for AI agents. + +## Install + +```bash +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 +- [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 [portal.trustwallet.com](https://portal.trustwallet.com). diff --git a/agent-sdk/authentication.md b/agent-sdk/authentication.md new file mode 100644 index 0000000..d1cfad5 --- /dev/null +++ b/agent-sdk/authentication.md @@ -0,0 +1,84 @@ +# 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 [portal.trustwallet.com](https://portal.trustwallet.com) +2. Create an app, then create an API key inside it +3. Copy your **Access ID** and **HMAC Secret** — the secret is shown only once + +## 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 +``` + +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: + +``` +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` | +| `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 `Authorization` header. Four headers are required on every 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 +ACCESS_ID="$TWAK_ACCESS_ID" +NONCE=$(uuidgen | tr -d '-') +DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") +METHOD="GET" +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) + +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" \ + -H "Authorization: $SIGNATURE" +``` + +## Security best practices + +- 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/cli-reference.md b/agent-sdk/cli-reference.md new file mode 100644 index 0000000..6e10943 --- /dev/null +++ b/agent-sdk/cli-reference.md @@ -0,0 +1,331 @@ +# CLI Reference + +The `twak` CLI provides full access to the Trust Wallet Agent SDK from the command line. + +**Run:** `npx @trustwallet/cli ` or install globally with `npm install -g @trustwallet/cli` + +--- + +## init + +Initialize configuration and save credentials. + +```bash +twak init --api-key --api-secret +``` + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | Yes | TWAK API access ID | +| `--api-secret` | Yes | HMAC secret | + +Credentials are saved to `~/.twak/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 [--no-keychain] [--json] +``` + +### wallet address + +```bash +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] +``` + +### wallet balance + +```bash +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. + +```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 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 status + +```bash +twak wallet status [--json] +``` + +--- + +## transfer + +```bash +twak transfer --to
--amount --token \ + [--confirm-to
] [--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 + +```bash +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. + +--- + +## price + +```bash +twak price [--chain ] [--json] +``` + +Chain is auto-detected from native token symbols (ETH, BNB, SOL, etc.). + +--- + +## 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). + +--- + +## search + +```bash +twak search [--networks ] [--limit ] [--json] +``` + +--- + +## trending + +```bash +twak trending [--category ] [--sort ] [--limit ] [--json] +``` + +Categories: `ai`, `rwa`, `memes`, `defi`, `dex`, `bnb`, `eth`, `sol`, `pumpfun`, `bonk`, `launchpad`, `launchpool`, `layer1`. + +Sort fields: `price_change` (default), `market_cap`, `volume`. + +--- + +## dapps + +Browse featured DApps and protocols. + +```bash +twak dapps [--category ] [--search ] [--categories] [--limit ] [--json] +``` + +Categories: `defi`, `dex`, `lending`, `nft`, `gaming`, `social`. Use `--categories` to list all available. + +--- + +## 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 \ + [--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 +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] +``` + +--- + +## serve + +Start an MCP server (stdio) or REST API server for AI agent integrations. + +```bash +twak serve [--rest] [--port ] [--host ] \ + [--auto-lock ] [--password ] \ + [--x402] [--payment-amount ] [--payment-asset ] \ + [--payment-chain ] [--payment-recipient
] +``` + +| 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 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. diff --git a/agent-sdk/quickstart.md b/agent-sdk/quickstart.md new file mode 100644 index 0000000..2e28e3b --- /dev/null +++ b/agent-sdk/quickstart.md @@ -0,0 +1,116 @@ +# Quickstart + +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 +npx @trustwallet/cli --version +``` + +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: + +```bash +twak init --api-key your_access_id \ + --api-secret your_hmac_secret +``` + +Credentials are stored in `~/.twak/credentials.json` (file permissions `0600`). This is the recommended approach for local development. + +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 +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 +``` + +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 + +# 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 + +# 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 + +# 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 +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