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

# Payments

> How paid resources are priced, authorized with signed vouchers, and settled on Solana through an escrow.

Resource providers can charge per call. Payments are made in SOL (priced in lamports) from a caller's on-chain escrow, settled by an **operator** service.

<Warning>
  Payments are under active development and have only been exercised on a local Solana validator. Don't use real funds.
</Warning>

## Pricing a function

Add a `paymentManifest` to any function on a resource you register:

```typescript {9-12} theme={null}
functions: [
  {
    name: "temperature",
    parameters: [{ name: "city", type: "string" }],
    returnType: "int32",
    exec: async (args) => {
      /* ... */
    },
    paymentManifest: {
      costLamports: 10000,
      recipientAddress: process.env.RECIPIENT_ADDRESS!,
    },
  },
],
```

| Field | Purpose |
| - | - |
| `costLamports` | Price of one call, in lamports |
| `recipientAddress` | Solana address that receives the provider's share |

The manifest is published with the resource, so callers see the price during discovery.

## How a paid call works

```mermaid theme={null}
sequenceDiagram
  participant C as Caller node
  participant P as Provider node
  participant O as Operator
  participant S as Solana escrow
  C->>P: POST /v1/run/resource + signed voucher
  P->>P: Verify voucher, run exec
  P-->>C: Result
  P->>O: POST /v1/payment (voucher)
  O->>S: Withdraw amount from caller's escrow
  S-->>P: 80% to provider recipient
  S-->>O: 20% to protocol fee wallet
```

1. When a request calls a priced remote function, the caller node creates a **payment voucher**: the amount, recipient, request and invocation IDs, the resource path, name, and parameters, and an expiry. It signs the voucher with its Ed25519 signing key. Callers refuse to pay more than 10,000 lamports per call.
2. The provider node verifies the voucher's signature, then runs the function and returns the result.
3. After a successful call, the provider submits the voucher to the operator.
4. The operator verifies the voucher and withdraws the amount from the caller's escrow. Each withdrawal pays **80%** to the provider's `recipientAddress` and **20%** to the protocol fee wallet.

## Escrow accounts

Each caller has an escrow account: a program-derived address owned by the Stellarium escrow program, derived from the operator's authority and the caller's user address. The caller's user address is the Solana address of their node's Ed25519 public key.

The operator creates the escrow and pays its rent and transaction fees. The caller then funds it with an ordinary SOL transfer; only the balance above the rent reserve is spendable.

## The operator

The operator is a service that creates escrows and submits withdrawals. Its signer is the escrow program's compiled authority. It exposes:

| Route | Purpose |
| - | - |
| `POST /v1/escrow` | Create the escrow for `{ "user": "<USER_ADDRESS>" }`. Returns `escrowAddress` and the transaction `signature`, or `status: "existing"` if it already exists. |
| `POST /v1/payment` | Settle a signed voucher. Records a receipt and returns the withdrawal signature. |

To try the full flow locally, see [Run a local network](/node/local-network).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.