*Example of the registration flow*
-Add this skill so your agent knows to use it's AgentKit registration when accessing x402 endpoints: +# Step 3: Wrap x402 calls in the agent + +Use this in agents that call paid x402 APIs. Without this client, agents may go straight to payment instead of using their AgentKit registration. + +```typescript +import { createAgentkitClient } from '@worldcoin/agentkit' + +const agentkit = createAgentkitClient({ + signer: { + address: agentWallet.address, + chainId: 'eip155:8453', + type: 'eip191', + signMessage: message => agentWallet.signMessage(message), + }, +}) + +const response = await agentkit.fetch('https://api.example.com/data') +``` + +Use `agentkit.fetch` anywhere the agent would otherwise call `fetch` for x402-protected APIs. It tries AgentKit first, then leaves the normal x402 payment fallback in place. + +If you cannot change the agent's HTTP client, add the fallback skill: + ```bash npx skills add worldcoin/agentkit agentkit-x402 ``` -# Step 3: Wire the hooks-based server flow +# Step 4: Wire the hooks-based server flow The example below shows the maintained Hono wrapper path. AgentKit itself is not Hono-only: Express and Next.js route handlers can use the same hooks and low-level helpers from the [SDK Reference](/agents/agent-kit/sdk-reference). @@ -107,6 +136,7 @@ const hooks = createAgentkitHooks({ const resourceServer = new x402ResourceServer(facilitatorClient) .register(WORLD_CHAIN, evmScheme) + .register(BASE, new ExactEvmScheme()) .registerExtension(agentkitResourceServerExtension) const routes = { @@ -146,9 +176,9 @@ app.get('/data', c => { serve({ fetch: app.fetch, port: 4021 }) ``` -This example accepts payments on both World Chain and Base. AgentBook lookup automatically resolves against the canonical World Chain deployment — you do not need to pass a chain ID or pin a network. +This example accepts payments on both World Chain and Base. AgentBook lookup automatically resolves against the canonical World Chain deployment. -# Step 4: Configure the default mode and storage +# Step 5: Configure the default mode and storage This guide uses `free-trial` mode so registered human-backed agents get 3 free requests before the normal x402 payment flow resumes. `InMemoryAgentKitStorage` is fine for local testing, but production should persist both usage counters and nonces. @@ -156,12 +186,8 @@ This guide uses `free-trial` mode so registered human-backed agents get 3 free r import type { AgentKitStorage } from '@worldcoin/agentkit' class DatabaseAgentKitStorage implements AgentKitStorage { - async getUsageCount(endpoint: string, humanId: string) { - return db.getUsageCount(endpoint, humanId) - } - - async incrementUsage(endpoint: string, humanId: string) { - await db.incrementUsage(endpoint, humanId) + async tryIncrementUsage(endpoint: string, humanId: string, limit: number) { + return db.tryIncrementUsage(endpoint, humanId, limit) } async hasUsedNonce(nonce: string) { @@ -180,4 +206,4 @@ const hooks = createAgentkitHooks({ }) ``` -Need `discount` mode, Solana, custom AgentBook deployments, or the low-level validation helpers? Continue to the [SDK Reference](/agents/agent-kit/sdk-reference). +Need `discount` mode, custom AgentBook deployments, or the low-level validation helpers? Continue to the [SDK Reference](/agents/agent-kit/sdk-reference). diff --git a/agents/agent-kit/sdk-reference.mdx b/agents/agent-kit/sdk-reference.mdx index 4e970f5..02980a4 100644 --- a/agents/agent-kit/sdk-reference.mdx +++ b/agents/agent-kit/sdk-reference.mdx @@ -1,13 +1,11 @@ --- title: "SDK Reference" -description: "Reference for AgentKit modes, APIs, supported chains, and low-level helpers." +description: "Reference for AgentKit modes, APIs, EVM signatures, and low-level helpers." "og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" "og:description": "Reference for the AgentKit SDK surface and advanced integration behavior." "twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" --- -{/* cspell:ignore DEVNET */} - Use this page when you need the full AgentKit surface area. For the shortest path to a working setup, start with [Integrate AgentKit](/agents/agent-kit/integrate). ## Access modes @@ -22,6 +20,53 @@ Usage counters are tracked per human per endpoint. Two agents backed by the same `discount` mode requires `verifyFailureHook` to be registered on the facilitator. Without it, discounted underpayments fail settlement verification. +## Agent client APIs + +### `createAgentkitClient(options)` + +Use this client in agents that call paid x402 APIs. `agentkit.fetch` inspects `402 Payment Required` responses and retries once with a signed `agentkit` header when the response advertises `extensions.agentkit`. + +```typescript +import { createAgentkitClient } from '@worldcoin/agentkit' + +const agentkit = createAgentkitClient({ + signer: { + address: agentWallet.address, + chainId: 'eip155:8453', + type: 'eip191', + signMessage: message => agentWallet.signMessage(message), + }, +}) +``` + +| Option | Type | Description | +| --------- | ------------------------------------- | ----------- | +| `signer` | `AgentkitSigner` | Agent wallet identity and SIWE signing function. Required. | +| `fetch` | `typeof fetch` | Optional base fetch implementation. Defaults to `globalThis.fetch`. | +| `onEvent` | `(event: AgentkitFetchEvent) => void` | Optional callback for logging and debugging. | + +The client does not create x402 payments. It returns the original response unchanged when AgentKit is unavailable or cannot be used, so your existing x402 payment client can handle fallback. + +### `AgentkitSigner` + +```ts +type AgentkitSigner = { + address: string + chainId: string + type: 'eip191' | 'eip1271' + signMessage(message: string): Promise