Skip to content

Add QHooks read and unsigned-plan action provider - #1651

Draft
qhooks wants to merge 4 commits into
coinbase:mainfrom
qhooks:qhooks-read-prepare-v8
Draft

qhooks wants to merge 4 commits into
coinbase:mainfrom
qhooks:qhooks-read-prepare-v8

Conversation

@qhooks

@qhooks qhooks commented Nov 15, 2026 •

Copy link
Copy Markdown

Description

Add an opt-in QHooks ActionProvider with 31 pinned actions for public reads and unsigned plans, plus separately enabled feedback. It creates no wallet, accepts no private key and cannot sign, deploy or broadcast.

Eligible spot trade/launch attribution resolves explicit referrer → configured option → existing wallet public getAddress(), lazily. Reads never inspect the wallet. The public barrel exports only the provider, factory, error and options type.

The static catalog contains all 31 reviewed public tools, including competition, agent-profile and board preparation. Titles, annotations and exact input schemas match a committed catalog fixture. Development-only pin checks reject drift or unreviewed names; remote metadata cannot add runtime tools. Token-based quotes, Studio configuration strings, QProof queue opt-in and unique profile-tool names retain their constraints.

Feedback is separately default OFF. Only trusted host configuration allowFeedback: true permits send_feedback to send free text to the QHooks team; tool arguments cannot enable it. Feedback retains write annotations and there is no trade-description steering. Board/profile/join tools prepare wallet-signable material without posting or signing. agreement_jar and held order/RFQ tools remain absent.

Spot preparation independently validates the local request against every returned transaction: chain IDs, trader, token/side/amount, pinned targets and manager, exact input approval, canonical single-hop calldata, quote-derived minimum/slippage, fee/referrer/deadline and native value. Unknown selectors or extra wallet-operation fields fail closed. The router pays msg.sender; no trader ABI field is invented. The unsigned SHA-256 tuple detects alteration but does not authenticate the server or establish a market price.

Release dependency: QHooks must release the additive qhooks.trade-plan.v1 integrity metadata and per-transaction chainId before these clients can prepare spot trades. Older responses fail closed. Prepared for the signing wallet: the agent's own wallet or yours. No custody; we never hold keys.

Tests

Node 22.23.1: full AgentKit tsc --noEmit, provider ESLint/Prettier and 15 native Jest tests pass.

cd typescript
pnpm install --filter @coinbase/agentkit... --ignore-scripts --frozen-lockfile
pnpm --filter @coinbase/agentkit run check
pnpm --filter @coinbase/agentkit exec jest --runInBand --no-cache --coverage=false src/action-providers/qhooks

Tests use injected fixture transports only: all 31 tools over MCP and REST, 24 tampered spot-plan variants per transport (including rehashed attacker targets, unlimited approvals and native injection), schema drift, exact large amounts, unavailable states, default-off feedback, and no automatic retries. No real feedback/post, provider, paid planner, wallet signature or transaction was used. The PR stays draft pending upstream review and the contributing guide's manual example-chatbot validation; no chatbot output or transaction receipt is claimed.

Checklist

  • Documentation added to relevant READMEs
  • Patch changeset included

All QHooks commits are GitHub-signed and verified.

Add pinned QHooks market, stored QProof, perps, OTC and agreement read/prepare tools. No signer or executor.

Include native provider tests, documentation and a patch changeset.
@cb-heimdall

cb-heimdall commented Nov 15, 2026 •

Copy link
Copy Markdown

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/2
Emergency override progress: 0/5
These approvals do not satisfy normal or CODEOWNER requirements because the commit identity is unverified.
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 1
1 if authored by an app that is not allowlisted and lacks verified human attribution 0
Sum 2

@github-actions github-actions Bot added documentation Improvements or additions to documentation action provider New action provider typescript labels Nov 15, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

action provider New action provider documentation Improvements or additions to documentation typescript

Development

Successfully merging this pull request may close these issues.

2 participants