HashLock OTC

@hashlock-tech/mcp

Hashlock Markets — a camada de liquidação para a economia de agentes, como ferramentas MCP. OTC cross-chain sem custódia: RFQ selado + negociação de preço + liquidação atômica HTLC — ambas as pernas liquidam ou ambas reembolsam; sem ponte, sem custodiante, sem risco de contraparte. BTC ↔ EVM / TRON.

⚠️ Somente testnets por enquanto (Ethereum Sepolia · TRON Nile · Bitcoin signet). A mainnet virá após a etapa de endurecimento de segurança — não envie fundos reais.

O que é isso?

O servidor canônico Model Context Protocol para Hashlock Markets. Ele dá aos agentes de IA (Claude, Cursor, Windsurf, qualquer cliente MCP) o ciclo completo de negociação OTC:

1. Navegue pelo registro de ativos e pelo quadro público de RFQ
2. Publique um RFQ público ou uma ordem privada de preço fixo (link compartilhável)
3. Responda a solicitações com um preço; negocie (contraproposta / aceitar / recusar) no thread da negociação
4. Concorde — ambas as partes aceitam → um swap HTLC é criado
5. Acompanhe a liquidação — quem financiou, timelocks, hashes de tx — e gerencie endereços de recebimento/reembolso

A assinatura da liquidação (financiamento e reivindicação dos HTLCs) permanece com sua própria carteira — o servidor nunca detém chaves ou fundos. O segredo do swap é gerado localmente na sua máquina e apenas seu hashlock sha256 é enviado; recupere-o com get_deal_secret quando for hora de reivindicar.

Duas formas de executar

• Local (stdio) — o pacote npm abaixo. Você o executa na sua máquina com suas próprias chaves; ele pode liquidar autonomamente (login SIWE + assinatura on-chain com HASHLOCK_*_KEY). Confiança total em você mesmo.
• Remoto (hospedado, Streamable HTTP) — uma URL pública (https://dev.hashlock.markets/mcp) que qualquer pessoa pode adicionar a partir do Claude / ChatGPT / qualquer cliente MCP; OAuth com um clique, sem instalação. Multi-tenant, portanto é estritamente sem custódia: a liquidação retorna transações não assinadas que você assina com sua própria carteira, e o servidor nunca detém chaves ou o seu preimage do swap. Veja Remoto (hospedado) abaixo.

Instalação

stdio local via npx (configuração mcpServers do Claude Desktop / Cursor / Windsurf):

{
  "mcpServers": {
    "hashlock": {
      "command": "npx",
      "args": ["-y", "@hashlock-tech/mcp"],
      "env": {
        "HASHLOCK_EVM_KEY": "0x<agent EVM key (TESTNET!)>",
        "HASHLOCK_TRON_KEY": "<agent TRON key, 64-hex (optional)>",
        "HASHLOCK_BTC_KEY": "<agent BTC WIF, signet (optional)>"
      }
    }
  }
}

Autenticação — autônoma, por cadeia

O agente possui sua(s) chave(s); o servidor faz o login por conta própria (nonce → assinar → JWT, renovado na expiração). A primeira chave configurada (EVM → TRON → BTC) cria a sessão; cada chave também assina a liquidação em sua cadeia.

Variável de ambiente	Cadeia	Login
HASHLOCK_EVM_KEY	EVM	SIWE personal_sign
HASHLOCK_TRON_KEY	TRON	signMessageV2
HASHLOCK_BTC_KEY	Bitcoin	BIP-322
HASHLOCK_TOKEN	—	um JWT pronto (alternativa a uma chave)

Sem nenhuma definida, as ferramentas somente leitura (list_assets, list_open_rfqs, get_rfq) ainda funcionam. Use chaves testnet dedicadas.

Outras variáveis de ambiente: HASHLOCK_API_URL (padrão https://dev.hashlock.markets/api), HASHLOCK_APP_URL (links de compartilhamento; padrão derivado), HASHLOCK_EVM_RPC (padrão um RPC público da Sepolia), HASHLOCK_TRON_HOST (padrão Nile), HASHLOCK_SECRETS_PATH (padrão ~/.hashlock/mcp-secrets.json, modo 0600).

Remoto (hospedado)

O mesmo servidor também roda como um MCP remoto via Streamable HTTP para que qualquer pessoa possa se conectar por URL — sem instalação. Esta é a superfície multi-tenant, sem custódia: navegue, faça RFQ, negocie e obtenha transações não assinadas de financiamento/reivindicação/reembolso que você assina com sua própria carteira (não há assinatura autônoma com chave em variável de ambiente nem armazenamento de segredos no servidor aqui — você fornece seu próprio hashlock e mantém seu próprio preimage).

Conecte-se a partir de um cliente: adicione a URL do servidor. Nada mais — o cliente descobre que precisa de autorização, envia você para o Hashlock para entrar e aprovar, e recebe sua própria chave:

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

A concessão então aparece em Developers como uma chave de API comum e pode ser revogada lá a qualquer momento. Clientes que não falam OAuth ainda podem enviar uma chave que criaram eles mesmos como Authorization: Bearer hk_….

Como funciona o fluxo OAuth

OAuth 2.1 padrão, então qualquer cliente MCP compatível o conduz sem supervisão:

Etapa	Endpoint
Chamada não autorizada nomeia seus metadados	401 + WWW-Authenticate: … resource_metadata=… (RFC 9728)
Cliente lê o recurso + metadados do servidor	/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server (RFC 8414)
Cliente se registra	POST /oauth/register (RFC 7591)
Você entra e aprova, no navegador	/oauth/authorize
Cliente troca o código por uma chave	POST /oauth/token — PKCE S256 obrigatório (RFC 7636)

Os códigos são de uso único e expiram em 60 segundos; URIs de redirecionamento estão na lista de permissões, com loopback permitido conforme RFC 8252. O token emitido É a chave de API, então uma concessão é revogável na mesma lista que qualquer outra chave.

Somente testnets até a etapa de endurecimento.

Execute o serviço hospedado você mesmo:

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

Variáveis de ambiente: HASHLOCK_V1_URL (base da API de desenvolvedor, padrão https://api.hashlock.markets/v1) · PORT (padrão 8080). Coloque-o atrás do seu proxy reverso em /mcp; GET /health é uma sonda de liveness.

Ferramentas (16)

Ferramenta	O que faz
list_assets	Registro de ativos (refs SYMBOL@chain, decimais)
list_open_rfqs	Quadro público de RFQ, filtrável
get_rfq	Um RFQ / ordem privada
create_rfq	Publicar um RFQ público ou ordem privada de preço fixo
cancel_rfq	Cancelar sua própria solicitação
respond_to_rfq	Responder com um preço → abre um thread de negociação
negotiate	message / propose / accept_proposal / accept / reject
my_rfqs, my_deals	Suas solicitações e threads de negociação
deal_status	Thread + histórico de negociação + estado do swap HTLC
set_settlement_address	Seu endereço de recebimento/reembolso por cadeia
get_deal_secret	O preimage do swap armazenado localmente (condicionado a ambas as pernas financiadas)
reveal_claim	Relatar uma reivindicação fora da banda (segredo + tx) para que a outra perna liquide
whoami	A conta na qual você está autenticado
fund_leg	Autônomo: financiar seu lado de um swap on-chain com a chave própria do agente (EVM/TRON/BTC)
claim_leg	Autônomo: reivindicar sua perna de recebimento com o preimage (revela o segredo on-chain)

Os valores são strings decimais legíveis ("0.5"); os preços são o total do ativo de cotação, não por unidade. Erros retornam um envelope estruturado { error: { code, is_retryable, recovery_hint } } no qual os agentes podem ramificar.

Loop totalmente autônomo

Com uma chave definida para cada cadeia que um swap toca, um agente pode executar de ponta a ponta sem humano: create_rfq/respond_to_rfq → negotiate (aceitar) → set_settlement_address (ambas as cadeias) → fund_leg → claim_leg. O financiamento/reivindicação é assinado localmente com as chaves do agente; o segredo do swap é gerado + armazenado localmente e apenas seu hashlock sai da máquina. Use chaves testnet dedicadas.

Como funciona a liquidação atômica

Ambas as partes bloqueiam fundos em HTLCs vinculados ao mesmo hashlock sha256(secret) — BTC como script P2WSH, EVM/TRON como contratos. O iniciador financia a perna de timelock longo primeiro (timelocks assimétricos, para que ninguém obtenha uma opção gratuita). Reivindicar uma perna revela o segredo on-chain, o que desbloqueia a outra perna. Ou ambas as pernas liquidam, ou ambas reembolsam após seus timelocks. O destinatário de cada perna é fixado no momento do financiamento — revelar o segredo não pode redirecionar fundos.

Desenvolvimento

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

Node ≥ 20. MIT.