---
name: protocol-api-key-integration
description: Safely connect API keys for trading protocols and venue SDKs without exposing secrets; use read/health/preview first, live execution double-gated.
triggers:
  - connect protocol API keys
  - Pear Protocol keys
  - Hyperliquid protocol keys
  - add venue API key
  - trading SDK credentials
  - ChangeNOW API key
  - BTC to ETH convert in Oracle
---

> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.


# Protocol API key integration

Use when DEMI wants Pear Protocol, Hyperliquid-adjacent tools, ChangeNOW convert, or any trading protocol API keys connected to the agent stack.

## Hard rules
- Never accept key values in chat, prompts, or tool args.
- Never print secrets. Health output reports present/source/value redacted only.
- Main/capital wallet is not an automated signer.
- Prefer agent/API wallets that cannot withdraw.
- Install credentials through owner-only files or a local prompt that never echoes values.
- Start with read/health/preview; live orders stay disabled until explicit GO plus caps.

## API-key-gated aggregators (0x / 1inch)

For aggregator adapters, “wired” and “configured” are different. Code/tests can prove the prepare path with fake keys, but live routes still require real keys installed in owner-only env.

- 0x uses `ZEROX_API_KEY` / `0X_API_KEY`; health with no key should report `configured:false` / key-missing, not pretend the provider is down.
- 1inch uses `ONEINCH_API_KEY`; executable `/swap` and `/approve/spender` are key-gated. Slippage for 1inch Classic Swap API is percentage points (`0.3` = 30 bps).
- Do not paste keys into chat or test fixtures. Unit tests may pass `{ apiKey: "test-key" }` only against mocked `fetchImpl`; never claim that means live configuration.
- After adding keys, verify with redacted health and one tiny fresh quote/prepare smoke; never print returned auth headers, raw key values, or env file contents.

## ChangeNOW multi-asset convert (BTC↔ETH / any ticker)
Hosted deposit-address rail when DEX+bridges cannot cover **native BTC** or awkward pairs. No good fully on-chain BTC→ETH path in Oracle today.

- Provider: `multiagent-desk` catalog `changenow` (`src/data/providers/changenow.mjs`).
- Ops: health · currencies · minAmount · estimate/convertQuote · createExchange · status.
- **Prepare-only:** create returns deposit address; user funds it; Oracle never custodies unless separate GO to fund deposit from agent.
- Currencies public; **estimate/create need** `CHANGENOW_API_KEY` (`x-changenow-api-key`). Health reports `keyConfigured` honestly.
- Env: `CHANGENOW_API_KEY`, optional `CHANGENOW_API_URL`. Never paste keys in chat.
- Prefer desk DEX/bridges for EVM↔EVM. Full detail: `references/changenow-convert.md` + repo `docs/CHANGENOW_CONVERT.md`.

## Standard implementation shape
1. Pick the right repo/surface.
   - Internal cross-venue/cross-chain tooling: `multiagent-desk`.
   - Public RH product/site/API/MCP: only if DEMI explicitly asks; RH product normally stays RH-only.
2. Create a root/user-only env or secret file.
   - Directory mode `0700`.
   - File mode `0600` or `0400`.
   - Refuse group/other-readable files.
3. Parse dotenv manually; do not shell-source untrusted secret files inside agent code.
4. Merge precedence: owner-only file first, environment overrides second.
5. Add redacted health output:
   - file exists/mode
   - credential present true/false
   - SDK installed true/false
   - endpoint reachable/auth-required status
   - live gates true/false
6. Add preview builders that validate symbol, size, notional cap, and return `dryRun:true`, `executable:false` by default.
7. Add tests before production code:
   - bad permissions rejected
   - redacted status contains no raw secret substring
   - live execution refuses when gates are off
   - preview validates amount/cap without sending an order
8. Live execution gate ladder:
   - protocol key installed
   - agent wallet approved/funded if required
   - global execute gate on
   - protocol-specific trade gate on
   - per-symbol/venue allowlist
   - max notional cap
   - fresh quote/sim/preview
   - explicit DEMI GO

## Pear + Hyperliquid case
See `references/pear-hyperliquid-keys.md` for the current `multiagent-desk` implementation pattern, commands, and Pear SDK quirks.

## Documenting key setup for OTHER people (open-source SETUP.md)

When the project ships to strangers, the same rules become **docs**, and DEMI asks
for them by name ("fix the read mes on how to set up, ie api for hyperliquid api
for polymarket keys and how they are stored etc"). Put it in a dedicated
`SETUP.md` and link it prominently from the README — buried key docs mean people
export secrets however they guess.

Cover, in this order:

1. **The two planes, stated first.** Read/prepare needs no key; execute always
   does. A prepared artifact is inert until something signs it. Without this
   framing every later instruction reads as "give the tool your key".
2. **What each key unlocks AND what still works without it** — as a table. People
   need to know they can evaluate the thing before handing over credentials.
   Hyperliquid reads are keyless; Polymarket market data is keyless.
3. **Per-venue credential shape**, because they differ structurally:
   - **Hyperliquid issues no API key.** An owner-local signer authorizes requests
     with a dedicated **API wallet** (`app.hyperliquid.xyz/API`) that can trade but
     **cannot withdraw**. The key stays in the protected local signer vault and is
     never passed through chat, prompts, arguments, or inherited environment.
   - **Polymarket needs two different things**: L2 API credentials
     (`API_KEY`/`API_SECRET`/`API_PASSPHRASE`) for CLOB order posting, *and* an
     owner-local signer for the Polygon wallet that owns the funds. Conflating
     them wastes an hour; neither credential belongs in model context.
4. **Storage is owner-local and fail closed.** Use the documented protected `0600`
   key-file and encrypted signer-vault workflow. Never print, paste, or interpolate
   key material into shell commands, chat, prompts, or process arguments.
5. **What the encryption does NOT protect.** A vault defends backups, cloud sync,
   and stolen disks at rest; it does **not** defend malware running as the user
   while the process is unlocked. Overselling a file-level scheme is worse than
   shipping none, because it changes behaviour.
6. **Both trade paths side by side** — non-custodial (Oracle prepares, user's
   wallet signs) and automated owner-local execution (the signer submits only
   after the user's explicit bounded authorization, including an explicitly
   configured shadow-profit promotion rule) — so the reader picks deliberately
   rather than defaulting into custody.

Also state where credentials travel: pinned provider endpoints, key dropped
rather than forwarded when a `baseUrl` is redirected or downgraded to `http://`.

### Arguing for a model router without overclaiming

When the project is a library, say plainly that **any** provider works (it is
just functions plus an MCP server), then make the specific case for Hermes:
per-profile routing matches a stack whose workloads have opposite needs —
cheap/wide for research, fast for execution (latency is money), strongest for
risk review, small for unattended crons — and the research profile can hold **no
signing key at all**.

Ground it in evidence rather than adjectives. The strongest available argument is
a multi-lineage audit result: four model families reviewed this codebase and each
found a CRITICAL the others missed, so one model reviewing its own work would
have shipped three of them. That is a fact about blind spots, not a vendor pitch.

## Reporting format
Use terse plain labels:
- Status: connected / missing keys / preview-only / live disabled
- Gates: global, protocol, cap
- Agent wallet: address only
- Secrets: present or missing, value redacted
- Next: exact local/SSH step for DEMI to install keys without pasting them