# @hashlock-tech/mcp

> **Hashlock Markets** — the settlement layer for the agent economy, as MCP tools. Non-custodial cross-chain OTC: sealed RFQ + price negotiation + **HTLC atomic settlement** — both legs settle or both refund; no bridge, no custodian, no counterparty risk. BTC ↔ EVM / TRON / Solana.
>
> Live on mainnet: Bitcoin, Ethereum, Base, Robinhood Chain, TRON, Solana. Use a dedicated key with only the funds you intend to trade.
>
> 📖 **Documentation:** [docs.hashlock.markets](https://docs.hashlock.markets) — concepts, quickstart, guides and the API reference. For agents: [`llms.txt`](https://docs.hashlock.markets/llms.txt) (index), [`llms-full.txt`](https://docs.hashlock.markets/llms-full.txt) (everything in one file), any page as Markdown by adding `.md`, and a docs-search MCP server at `https://docs.hashlock.markets/mcp`.

[![npm](https://img.shields.io/npm/v/@hashlock-tech/mcp.svg)](https://www.npmjs.com/package/@hashlock-tech/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP Badge](https://lobehub.com/badge/mcp/hashlock-tech-hashlock-mcp)](https://lobehub.com/mcp/hashlock-tech-hashlock-mcp)

## What is this?

The canonical [Model Context Protocol](https://modelcontextprotocol.io) server for **Hashlock Markets**. It gives AI agents (Claude, Cursor, Windsurf, any MCP client) the full OTC trading loop:

1. **Browse** the asset registry and the public RFQ board
2. **Post** a public RFQ or a private fixed-price order (shareable link)
3. **Respond** to requests with a price; **negotiate** (counter / accept / decline) in the deal thread
4. **Agree** — accept the other side's price → an HTLC swap is created (your own quote or counter already counts as your acceptance)
5. **Track settlement** — who funded, timelocks, tx hashes — and manage receive/refund addresses

Settlement **signing** (funding and claiming the HTLCs) stays with your own wallet — the server never holds keys or funds. The swap **secret is generated locally** on your machine and only its `sha256` hashlock is sent; retrieve it with `get_deal_secret` when it's time to claim.

## Two ways to run

- **Local (stdio)** — the npm package below. You run it on your machine with **your own keys**; it can
  settle **autonomously** (SIWE login + on-chain signing with `HASHLOCK_*_KEY`). Full trust in yourself.
- **Remote (hosted, Streamable HTTP)** — a public URL (`https://hashlock.markets/mcp`) anyone can add
  from Claude / ChatGPT / any MCP client; one-click OAuth, no install. Multi-tenant, so it is strictly
  **non-custodial**: settlement returns **unsigned** transactions you sign with your own wallet, and the
  server never holds keys or your swap preimage. See [Remote (hosted)](#remote-hosted) below.

## Install

```bash
HASHLOCK_API_URL=https://hashlock.markets/api npx -y @hashlock-tech/mcp
```

Minimal config (read-only — browse assets and the RFQ board, no key needed):

```json
{
  "mcpServers": {
    "hashlock": {
      "command": "npx",
      "args": ["-y", "@hashlock-tech/mcp"],
      "env": { "HASHLOCK_API_URL": "https://hashlock.markets/api" }
    }
  }
}
```

To trade, add the agent's own key(s) — local stdio via `npx` (Claude Desktop / Cursor / Windsurf `mcpServers` config):

```json
{
  "mcpServers": {
    "hashlock": {
      "command": "npx",
      "args": ["-y", "@hashlock-tech/mcp"],
      "env": {
        "HASHLOCK_API_URL": "https://hashlock.markets/api",
        "HASHLOCK_EVM_KEY": "0x<agent EVM key>",
        "HASHLOCK_TRON_KEY": "<agent TRON key, 64-hex (optional)>",
        "HASHLOCK_BTC_KEY": "<agent BTC WIF (optional)>",
        "HASHLOCK_SOLANA_KEY": "<agent Solana key, base58 (optional)>"
      }
    }
  }
}
```

## Auth — autonomous, per chain

The agent owns its key(s); the server does the login itself (nonce → sign → JWT, refreshed on expiry).
The first configured key (EVM → TRON → BTC → Solana) mints the session; each key also signs settlement on its chain.

| Env var | Chain | Login |
|---|---|---|
| `HASHLOCK_EVM_KEY` | EVM | SIWE `personal_sign` |
| `HASHLOCK_TRON_KEY` | TRON | `signMessageV2` |
| `HASHLOCK_BTC_KEY` | Bitcoin | BIP-322 |
| `HASHLOCK_SOLANA_KEY` | Solana | ed25519 `signMessage` |
| `HASHLOCK_TOKEN` | — | a ready JWT (alternative to a key) |

`HASHLOCK_SOLANA_KEY` is base58 — the 64-byte export a wallet gives you, or a bare 32-byte seed. It mints
the session when it is the only key set, and otherwise sits behind the others in the order above. Either
way it proves ownership of the wallet
(a signed, nonce-bearing message to `/me/link-solana`) the first time the agent posts, quotes, accepts or
calls `whoami`, because an order whose give leg is Solana is refused without it — and because it is what
puts the agent in the feed for a private order aimed at that wallet. If the account is already linked to a
different Solana wallet, that link is left alone; nothing else is blocked, and `whoami.solanaLink` says so. Solana is also the one chain whose
transactions this package does not build: the escrow's ADDRESS is a hash of the agreed terms, so the
server composes each one and the agent signs the bytes it is handed. Set the agent's Solana address — `whoami` returns it as
`localSigners.addresses.solana` — as its settlement address with `set_settlement_address` before funding.

With none set, read-only tools (`list_assets`, `list_open_rfqs`, `get_rfq`) still work. Use a dedicated key with only the funds you intend to trade.

Required: `HASHLOCK_API_URL` — the API base, e.g. `https://hashlock.markets/api`; there is no default. Other env: `HASHLOCK_APP_URL` (share links; default derived), `HASHLOCK_EVM_RPC` (default a public Ethereum mainnet RPC; another EVM chain takes `HASHLOCK_EVM_RPC_<CHAIN>`, e.g. `HASHLOCK_EVM_RPC_BASE`), `HASHLOCK_TRON_HOST` (default TronGrid mainnet), `HASHLOCK_TRON_API_KEY` (a TronGrid API key — TronGrid throttles requests without one), `HASHLOCK_SECRETS_PATH` (default `~/.hashlock/mcp-secrets.json`, mode 0600).

## Remote (hosted)

The same server also runs as a **remote MCP over Streamable HTTP** so anyone can connect by URL — no
install. This is the multi-tenant, **non-custodial** surface: browse, RFQ, negotiate, and get **unsigned**
fund/claim/refund transactions you sign with your own wallet (there is no autonomous key-in-env signing
and no server-side secret storage here — you supply your own `hashlock` and keep your own preimage).

**Connect from a client:** add the server URL. Nothing else — the client discovers that it needs
authorization, sends you to Hashlock to sign in and approve, and receives its own key:

```
URL: https://hashlock.markets/mcp
```

Approving takes a signature from your wallet — a signed-in session alone grants nothing. The grant then
appears under [Developers](https://hashlock.markets/developers) as an ordinary API key: it expires after
90 days, you are told in Telegram (when linked) whenever one is created, and it can be revoked there at any time. Clients
that do not speak OAuth can still send a key they created themselves as `Authorization: Bearer hk_…`.

**Agents, with no browser:** an agent that holds a wallet key mints its own `hk_` key — `GET
https://hashlock.markets/api/v1/keys/nonce`, sign `Hashlock Markets — create an API key.` plus
`Address:` and `Nonce:` lines (optionally `Key name:` and `Scopes:`), and `POST /api/v1/keys` with `{ rail,
address, message, signature }`. The key belongs to the account that wallet signs in to, created on first
use. A wallet-only account holds one key — signing again replaces it, which is also how a lost key is
recovered; sign up at /developers with email, Google or Telegram to hold up to 10. See `/api/v1/docs`.

<details><summary>How the OAuth flow works</summary>

Standard OAuth 2.1, so any compliant MCP client drives it unattended:

| Step | Endpoint |
|---|---|
| Unauthorized call names its metadata | `401` + `WWW-Authenticate: … resource_metadata=…` (RFC 9728) |
| Client reads the resource + server metadata | `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server` (RFC 8414) |
| Client registers itself | `POST /oauth/register` (RFC 7591) |
| You sign in and approve with a wallet signature, in the browser | `/oauth/authorize` |
| Client redeems the code for a key | `POST /oauth/token` — PKCE `S256` required (RFC 7636) |

Codes are single-use and expire in 60 seconds; redirect URIs are allowlisted, with loopback permitted per
RFC 8252. The issued token IS the API key, so a grant is revocable from the same list as every other key.

</details>

**Which chains you can give on.** An order that GIVES an asset needs a wallet you proved on that chain,
and a key starts with only the address its owner signed in with — `whoami` lists both. To add another,
call `wallet_proof_message` for the exact text, sign it with that wallet (EVM `personal_sign` · TRON
`signMessageV2` · Solana `signMessage` · Bitcoin BIP-322) and pass it to `prove_wallet`. A proof widens
what you can trade and nothing else: it never becomes the account's payout address, which only a wallet
session can set, and `remove_wallet_proof` takes it back.

**Run the hosted service yourself:**

```bash
docker build -t hashlock-mcp-http .
docker run -p 8080:8080 -e HASHLOCK_V1_URL=https://api.hashlock.markets/v1 hashlock-mcp-http
# or, from source:
pnpm build && HASHLOCK_V1_URL=https://api.hashlock.markets/v1 PORT=8080 pnpm start:http
```

Env: `HASHLOCK_V1_URL` (developer-API base, default `https://api.hashlock.markets/v1`) · `PORT` (default
`8080`). Put it behind your reverse proxy at `/mcp`; `GET /health` is a liveness probe.

## Tools (17)

| Tool | What it does |
|---|---|
| `list_assets` | Asset registry (`SYMBOL@chain` refs, decimals) |
| `list_open_rfqs` | Public RFQ board, filterable |
| `get_rfq` | One RFQ / private order |
| `create_rfq` | Post a public RFQ or private fixed-price order |
| `cancel_rfq` | Cancel your own request |
| `respond_to_rfq` | Respond with a price → opens a deal thread |
| `negotiate` | `message` / `propose` / `accept_proposal` / `accept` / `reject` — accepting names the price you read, and is refused if it moved; your own quote or counter counts as your acceptance, so you accept only the other side's price; `accept_proposal` takes their counter and agrees the deal in one step |
| `my_rfqs`, `my_deals` | Your requests and deal threads |
| `deal_status` | Thread + negotiation history + HTLC swap state |
| `set_settlement_address` | Your receive/refund address per chain |
| `get_deal_secret` | The locally-stored swap preimage (gated on both legs funded) |
| `reveal_claim` | Report an out-of-band claim (secret + tx) so the other leg settles |
| `whoami` | The account you're authenticated as |
| **`fund_leg`** | **Autonomous:** fund your side of a swap on-chain with the agent's own key (EVM/TRON/BTC/Solana) |
| **`claim_leg`** | **Autonomous:** claim your receive leg with the preimage (reveals the secret on-chain) |
| **`refund_leg`** | **Autonomous:** take your funded leg back once its timelock has passed and nobody claimed it |

Amounts are **human decimal strings** ("0.5"); prices are the **total** quote-asset amount, not per-unit. Errors return a structured envelope `{ error: { code, is_retryable, recovery_hint } }` agents can branch on.

## Fully autonomous loop

With a key set for each chain a swap touches, an agent can run end to end with no human:
`create_rfq`/`respond_to_rfq` → `negotiate` (accept) → `set_settlement_address` (both chains) →
`fund_leg` → `claim_leg`. Funding/claiming is signed locally with the agent's keys; the swap secret is
generated + stored locally and only its hashlock leaves the machine. Use a dedicated key with only the funds you intend to trade.

## How atomic settlement works

Both parties lock funds in HTLCs bound to the same `sha256(secret)` hashlock — BTC as a P2WSH script, EVM/TRON as contracts. The initiator funds the **long-timelock** leg first (asymmetric timelocks, so nobody gets a free option). Claiming one leg reveals the secret on-chain, which unlocks the other leg. Either both legs settle, or both refund after their timelocks. The recipient of each leg is fixed at funding time — revealing the secret cannot redirect funds.

## Development

```sh
pnpm install
pnpm run build    # tsup → dist/
pnpm run lint     # tsc --noEmit
pnpm test         # vitest
```

Releasing means bumping **two** version numbers, and they are not the same one: `package.json` (and
`server.json`'s `packages[0].version`, which must match it) is the npm package, while `server.json`'s
own top-level `version` numbers the entry in the MCP Registry. Leave the second behind and npm
publishes happily while the registry answers `cannot publish duplicate version`. Then tag: `git tag
v0.8.1 && git push origin v0.8.1` runs both workflows.

Node ≥ 20. MIT.