# 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: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.