# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.trustwallet.com/developer/agent-sdk/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.