@oceanalt/agentkit-hook

A beforePayment hook for Coinbase AgentKit's x402 action provider. It runs after AgentKit's amount and network checks and before the signer is invoked:

1. Signed payment requirements. If the 402's PaymentRequired reaches the hook, the seller's extensions.signedRequirements (Ed25519) is verified offline, and the payTo about to be paid must be one the seller signed. A payTo rewritten in transit, or substituted outside the signed 402, is refused — screening a freshly generated address by reputation alone would find nothing.
2. Payee decision. The recipient gets a pre-settlement decision: allow, review or decline.

OceanAlt holds no keys and moves no money.

The hook is proposed in coinbase/agentkit#1454, which is open and not yet merged. This package targets its contract as of commit 92af548 (return undefined to allow, or { abort, reason?, code? }). If the contract changes before merge, this package will follow. Not affiliated with or endorsed by Coinbase.

npm i @oceanalt/core @oceanalt/agentkit-hook

import { OceanAltClient } from "@oceanalt/core";
import { createBeforePaymentHook } from "@oceanalt/agentkit-hook";

const x402 = new X402ActionProvider({
  registeredServices: ["https://seller.example"],
  beforePayment: createBeforePaymentHook({ client: new OceanAltClient() }),
});

Behaviour

| Situation | mode: "block" (default) | mode: "advise" | |---|---|---| | Signed requirements verify, payee allow | allow | allow | | Requirements tampered, payTo not signed by the seller, or verification key unavailable | abort requirements.<reason> | abort | | Payee decline | abort with the decision's reason code | abort | | Payee review, decision service unreachable, or unrecognised decision | abort | allow | | Selected option has no payTo | abort payee.missing | allow | | No signed requirements reached the hook | skipped, payee still screened | skipped | | …with requireSignature: true | abort requirements.missing | abort |

The integrity check only runs if the caller passes paymentRequirements / paymentRequirementsHeader from make_http_request into retry_http_request_with_x402. Those arguments are optional, so a model that does not thread them through silently disables the check. Set requireSignature: true if you want that case refused instead.

Every call leaves an intent → decision → outcome record via client.record().