> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# web3-wallet-worker Isolate Profile

> Comprehensive engineering specification for the Hoox EVM & DeFi On-Chain Wallet Worker, covering mnemonics, private keys, and smart contract signature routing.

The **`web3-wallet-worker`** is the on-chain gateway of the Hoox trading ecosystem. Running as an isolated private micro-worker, this service is responsible for securely managing EVM mnemonics and private keys (bound as encrypted Workers Secrets), querying multi-chain gas limits and token balances, executing native/ERC-20 transfers, and signing smart contract swap payloads (e.g. Uniswap/1inch routers) via JSON-RPC providers.

***

## ⚡ 1. Declared Wrangler Configurations & Bindings

The `web3-wallet-worker` does not expose a public URL, communicating internally via V8 Service Bindings. Its `wrangler.jsonc` specifies:

```jsonc theme={null}
{
  "name": "web3-wallet-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-19",
  "compatibility_flags": ["nodejs_compat"],
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "vars": {
    "DEFAULT_CHAIN": "ethereum",
  },
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
  ],
  "secrets": [
    "INTERNAL_KEY_BINDING",
    "WALLET_MNEMONIC_SECRET",
    "WALLET_PK_SECRET",
    "RPC_PROVIDER_URL",
  ],
}
```

***

## 🔑 2. Environmental Variables & Encrypted Secrets

* **`WALLET_PK_SECRET`**: Encrypted private key used for single-account execution.
* **`WALLET_MNEMONIC_SECRET`**: Encrypted 12 or 24-word HD wallet seed phrase used to derive multiple accounts.
* **`RPC_PROVIDER_URL`**: High-availability HTTP Ethereum / EVM RPC provider (e.g., Infura, Alchemy, or QuickNode).
* **`INTERNAL_KEY_BINDING`**: Shared key used to validate calls from internal compute nodes.

### Local Development Mocking (`.dev.vars`)

```bash theme={null}
WALLET_PK_SECRET=0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
WALLET_MNEMONIC_SECRET="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
RPC_PROVIDER_URL=http://localhost:8545
INTERNAL_KEY_BINDING=dev_shared_internal_security_key
```

***

## 🔌 3. Internal REST API Specification

> **Note:** For the canonical endpoint directory with full request/response examples across all workers, see [`/docs/devops/api/endpoints`](../api/endpoints).

### A. Execute On-Chain Transaction

* **Endpoint**: `/process`
* **Method**: `POST`
* **Headers**: `X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>`
* **JSON Payload**:
  ```json theme={null}
  {
    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "payload": {
      "action": "sendTransaction",
      "chain": "arbitrum",
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "value": "0.05",
      "data": "0xa9059cbb000000000000000000000000...",
      "gasLimit": 100000
    }
  }
  ```
* **Success Response (200 OK)**:
  ```json theme={null}
  {
    "success": true,
    "result": {
      "txHash": "0x53a9284739ebfd10482da73cbcfd10482da73cbcfd10482da73cbcfd10482ab",
      "nonce": 142,
      "gasUsed": 64205,
      "effectiveGasPrice": "24000000000"
    },
    "error": null
  }
  ```

***

### B. Query Token Balance

* **Endpoint**: `/process`
* **Method**: `POST`
* **JSON Payload**:
  ```json theme={null}
  {
    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "payload": {
      "action": "getBalance",
      "chain": "polygon",
      "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "tokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f"
    }
  }
  ```
* **Success Response (200 OK)**:
  ```json theme={null}
  {
    "success": true,
    "result": {
      "balance": "1485.50",
      "symbol": "USDT",
      "decimals": 6
    },
    "error": null
  }
  ```

***

## 🛡️ 4. On-Chain Security Best Practices

Operating hot wallets on public blockchain networks introduces extreme security vectors:

* **Harden Private Keys**: **Never** write keys to wrangler config files or print them in telemetry logs. Always provision keys via encrypted Cloudflare Secrets.
* **Gas Price Limit Traps**: To prevent severe loss during network congestion or flash crashes, the worker enforces a **gas limit trap**—if current network gas price exceeds your KV configured limit (`web3:max_gas_price_gwei`), transactions are dropped before signing to prevent massive fee consumption.
* **Isolate Access**: All calls must originate internally via Service Bindings. The wallet worker does not bind to public ports, meaning external scrapers cannot send raw transaction payloads or try to brute-force auth codes.

***

<Tip>
  Testing on-chain logic locally? Use the Docker runtime stack (`hoox dev start   --runtime docker`) to launch an isolated Hardhat/Anvil node container and test
  private wallet swaps on a simulated local EVM fork safely!
</Tip>

### 🔗 Next Steps

* **[trade-worker Profile](trade-worker)** — Review how execution orders route transactions to EVM wallet nodes.
* **[D1 Database Operations](../../enduser/guides/database-ops)** — Manage your SQLite schemas and sync positions logs.