> For the complete documentation index, see [llms.txt](https://docs.northstar.sonicsvm.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.northstar.sonicsvm.org/build/fees.md).

# Programmable Economics

NorthStar sessions are gasless by default on devnet — but that's just one configuration of a fully-programmable fee market. Operators set their own economics per session: any fee schedule, any token, any revenue split.

## What's configurable per session

Every session opens with a `FeeStructure` parameter that decides:

* **Fee level** — gasless, sub-cent, or any amount the operator chooses.
* **Fee token** — SOL, USDC, the operator's own SPL token, or no token at all.
* **Revenue split** — the slice that goes to the grid operator vs. the protocol.
* **Per-instruction overrides** — different fee bands per workload (place\_intent vs. settle\_intent vs. data feeds).

The default `zero_fee_structure()` is a useful starting point for marketing demos and developer-experience flows. Production grids will run their own.

## Why programmable fees matter

Three direct consequences:

1. **Builders set their own runway.** A team running a market-data feed can charge per-read in their own token; a privacy-focused DeFi venue can charge premium fees for sealed-bid auctions; an agent-sandbox operator can subsidize the agent's transactions to remove user friction.
2. **Aggregators and wallets become operators.** A wallet that opens grids on behalf of users captures a share of the fees on every transaction in that grid. New revenue stream, no separate validator infrastructure.
3. **No protocol-level rent.** The protocol's take is a parameter, not a fixed tax. Operators can run thin margins for high-volume workloads or fat margins for premium ones.

## API surface

The `FeeStructure` is a parameter on the Portal program's `OpenSession` instruction. The full schema lives in the [SDK reference](https://github.com/mirrorworld-universe/northstar-docs/blob/main/reference/portal-program/README.md). A typical opening for a custom-fee grid looks like:

```typescript
import { NorthStarSDK, FeeStructure } from "@sonicsvm/northstar-sdk";

await sdk.openSession({
  gridId,
  ttlSlots: 86_400n,                    // ~ 24h at 400ms slots
  feeStructure: FeeStructure.custom({
    token: USDC_MINT,
    perTxLamports: 10_000n,             // ~ 0.001 USDC equivalent
    revenueSplitBps: 5_000,              // 50% to operator
  }),
});
```

## Roadmap

The SDK exposure of custom-fee configuration is tracked in [ENG-6886](https://linear.app/mirror-world/issue/ENG-6886). Three deliverables under that umbrella:

1. SDK + docs surface for what's already supported.
2. Custom-token fees (USDC + arbitrary SPL).
3. Revenue capture for grid operators.

## See also

* [Sessions](https://github.com/mirrorworld-universe/northstar-docs/blob/main/concepts/sessions/README.md) — what a session is and what's bound to one.
* [Settle-back guarantees](https://github.com/mirrorworld-universe/northstar-docs/blob/main/concepts/settle-back/README.md) — how state returns to L1 when a session closes.
* [Migrate from L1](https://github.com/mirrorworld-universe/northstar-docs/blob/main/build/migrate/README.md) — what changes when you move an existing program to a session.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.northstar.sonicsvm.org/build/fees.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.