# How the SDK works

> What the SDK observes and what your payment stack retains.

Source: https://docs.forgeintel.co/sdk/how-it-works

1. **Connect.** Give the SDK a Forge API key and mount its adapter outside your existing payment handler. The collector is built in. The SDK observes requests; it does not require a manual paid-route list.
2. **Observe.** Your auth, pricing and payment code still decide every response. The SDK identifies the agent behind each request and records how far it got, without changing what agents see.
3. **Review.** The SDK batches events to Forge in the background. The service's [Activity](https://docs.forgeintel.co/activity) page shows every agent session.

Agent context is off by default. With `agentContext: true` (`agent_context=True`), agents are invited to include their name and search query, and Forge records them when sent, but it stays optional. `{ required: true }` (`AgentContextOptions(required=True)`) rejects paid requests without it with HTTP 400 before payment processing. Caller-supplied context is not authenticated identity. [Configure agent context](https://docs.forgeintel.co/guides/agent-context).

Event capture does not call Forge on your API's response path. A collector outage can lose activity but does not change merchant responses. [Failure behavior](https://docs.forgeintel.co/guides/reliability).

## What the SDK reports

With just an API key, the SDK reports these events in the background, never on your request path:

| Event | When |
| --- | --- |
| `discovery` | An agent reads your OpenAPI document or a well-known file such as `/.well-known/x402`. |
| `challenge` | A request gets your x402 402 challenge. |
| `interaction` | A paid call completes, with payer, network, amount and settlement transaction. |
| `visit` | An agent requests anything else: your homepage, other pages, free routes. |

Visits show an agent's whole path through your service, from landing to payment. Forge only reports them for agents: a request signed with [Web Bot Auth](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/), or any client that isn't a browser. People browsing your site, and asset files (images, CSS, scripts, fonts), are never reported. A visit records the method, the path without its query string, the status, the response time and the client headers below; never bodies or query values. At most 120 visits a minute are reported per process, and never at the expense of challenges or paid calls.

Every event carries a fixed set of client headers, read by name and nothing else: `user-agent`, `x-client-id`, `x-session-id`, the wallet-address headers, `referer`, `payment-retry`, `cf-worker`, the Sentry release from `baggage`, and the Web Bot Auth headers `signature-agent`, `signature-input` and `signature`. Forge uses them to tell which agent and client made a call; Web Bot Auth signatures are cryptographic proof of the agent's operator.

Express, Hono, fetch handlers and Python (ASGI) see every request. In Next.js, Forge sees the routes you wrap with `withForge`, so visits cover those.