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

# The manifest

> The /.well-known/bankroll.json file your app serves so Bankroll knows what it is and how to pay it.

Every app declares itself with a JSON file served at
**`/.well-known/bankroll.json`** on its own origin. Bankroll fetches it over
HTTPS to learn your app's identity, the capabilities it uses, and the wallet that
receives payments. It is the root of trust for your integration: the host reads
it, never your page.

```json /.well-known/bankroll.json theme={null}
{
  "name": "Acme Games",
  "iconUrl": "https://acme.example/icon-256.png",
  "merchantWallet": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "capabilities": ["identity", "pay"]
}
```

## Fields

| Field            | Type      | Description                                                                                                                                                                          |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`           | string    | Your app's display name, shown to the user in the consent prompt.                                                                                                                    |
| `iconUrl`        | string    | HTTPS URL of your app icon (square, 256×256 recommended), shown in the consent prompt.                                                                                               |
| `merchantWallet` | string    | The wallet address that receives every payment from `pay()`. Fixed here — your page can never redirect funds elsewhere. **Required in every manifest**, even for identity-only apps. |
| `capabilities`   | string\[] | The capabilities your app uses: `"identity"`, `"pay"`, or both. The consent prompt asks only for what you declare.                                                                   |

## Rules

* **Served on your origin.** The manifest must live at the exact path
  `/.well-known/bankroll.json` on the same origin your app loads from. Bankroll
  matches by origin (scheme + host + port), so `https://acme.example` and
  `https://app.acme.example` are different apps with different manifests.
* **HTTPS only.** The manifest, `iconUrl`, and your app URL must all be HTTPS.
* **Fails closed.** If the manifest is missing, unreachable, or malformed, your
  app is granted **no** capability — calls to `identity()` and `pay()` reject
  (a missing or malformed manifest surfaces as the error code `manifest_error`).
* **Declares the ceiling.** A capability the user can be asked for must be listed
  here. Calling a capability you didn't declare rejects with
  `capability_not_registered`. See [error codes](/build/payments#error-codes).

<Note>
  The `merchantWallet` is the load-bearing security property of payments: because
  the recipient is pinned in a manifest the host fetches (not supplied by your
  page), a compromised page can at worst over-charge a consented amount to *your
  own* wallet — it can never send funds somewhere else.
</Note>

## Serving it

Serve the file with `Content-Type: application/json` at the well-known path. A
couple of common setups:

<CodeGroup>
  ```javascript Next.js (app router) theme={null}
  // app/.well-known/bankroll.json/route.ts
  export function GET() {
    return Response.json({
      name: "Acme Games",
      iconUrl: "https://acme.example/icon-256.png",
      merchantWallet: process.env.MERCHANT_WALLET,
      capabilities: ["identity", "pay"],
    });
  }
  ```

  ```javascript Express theme={null}
  app.get("/.well-known/bankroll.json", (_req, res) => {
    res.json({
      name: "Acme Games",
      iconUrl: "https://acme.example/icon-256.png",
      merchantWallet: process.env.MERCHANT_WALLET,
      capabilities: ["identity", "pay"],
    });
  });
  ```
</CodeGroup>

Verify it's live before testing your app:

```bash theme={null}
curl https://acme.example/.well-known/bankroll.json
```