> ## Documentation Index
> Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway SDK

> @faremeter/gateway-nginx generates the nginx + Lua config that turns API nodes into a payment-enforcing proxy.

`@faremeter/gateway-nginx` is the OSS package that lets a marketplace operator turn an OpenAPI spec into a working payment-enforcing nginx configuration. It is what the marketplace API nodes use under the hood. Most readers do not need to install it — but it helps to know what it does, because it shapes what publishers can express in their pricing.

**Package**: [`@faremeter/gateway-nginx`](https://github.com/faremeter/faremeter/tree/main/packages/gateway-nginx)

## What it does

The gateway SDK takes a parsed OpenAPI spec (with `x-faremeter-*` extensions) and emits two things:

* **nginx location blocks** — included by the operator inside their own `server { }` block. Each priced endpoint gets a Lua-instrumented location.
* **A bundled Lua module** (`faremeter.lua`) — referenced by the location blocks at runtime to talk to a sidecar process that evaluates pricing and validates payment.

```typescript theme={null}
import { generateConfig } from "@faremeter/gateway-nginx";

const { locationsConf, luaFiles, warnings } = generateConfig(input);
// locationsConf: string of nginx location blocks
// luaFiles: { "faremeter.lua": "..." }
```

`generateConfig` is a pure function — no I/O, no network — so it is safe to call in tests or build pipelines.

## How it fits

```
                                +-----------+
                                |  sidecar  |   evaluates pricing,
                                +-----------+   talks to facilitator
                                  ^   |
                         /request |   | JSON
                        /response |   v
+--------+    +-------------------+----------+    +-----------+
| client | -> |       nginx (OpenResty)      | -> | upstream  |
+--------+ <- |   Lua hooks the request,     | <- | (publisher|
              |   reads payment, forwards    |    |  backend) |
              |   to upstream when paid      |    +-----------+
              +------------------------------+
```

The Lua code generated by the SDK is stateless — all pricing decisions are made in the sidecar. The sidecar is the only component that imports `@faremeter/middleware` and the payment evaluator. nginx itself never imports Faremeter code; it just speaks HTTP/JSON to the sidecar via Unix socket.

For the full nginx phase model (`access_by_lua_block`, `header_filter_by_lua_block`, `body_filter_by_lua_block`, `log_by_lua_block`), see the [package's ARCHITECTURE.md](https://github.com/faremeter/faremeter/blob/main/packages/gateway-nginx/ARCHITECTURE.md).

## Capabilities a publisher can use

The pricing extensions in your OpenAPI spec map to features the SDK supports:

* **Three transports** — HTTP JSON, Server-Sent Events (SSE) streaming, and WebSocket frame relay. The transport is detected from the response and handled appropriately.
* **Method dispatch** — different pricing for `GET` vs `POST` on the same path.
* **Response field capture** — pricing can depend on response data (e.g. `usage.total_tokens` from an LLM response). The generator statically analyzes the spec and only parses chunks that could contain referenced fields.
* **Optional spec hosting** — serve the OpenAPI spec at `/.well-known/openapi.yaml` for discovery clients.

Static analysis means the generated config only does the work it needs to: an endpoint with a fixed price never inspects the response body.

## Prerequisites for operators

The generated config requires [OpenResty](https://openresty.org/) (nginx + LuaJIT) and the [lua-resty-http](https://github.com/ledgetech/lua-resty-http) module. The operator runs OpenResty, includes the generated `locationsConf`, and runs the sidecar process.

## Gateway-mode vs legacy

Gateway-mode (the path described above) is the current and recommended way to enforce payment at the proxy. The marketplace repo also contains a hand-written Lua access module from earlier work; new tenants should be on gateway-mode and existing tenants are being migrated.

## What's next

<CardGroup cols={2}>
  <Card title="Publisher path" icon="upload" href="/marketplace/publisher">
    Where the OpenAPI spec the SDK consumes comes from.
  </Card>

  <Card title="Self-hosting" icon="wrench" href="/marketplace/self-hosting">
    Run the SDK inside your own marketplace deployment.
  </Card>

  <Card title="Facilitators" icon="circle-check" href="/concepts/facilitators">
    What the sidecar talks to when validating and settling payment.
  </Card>

  <Card title="Package on GitHub" icon="github" href="https://github.com/faremeter/faremeter/tree/main/packages/gateway-nginx">
    README, ARCHITECTURE.md, and source.
  </Card>
</CardGroup>