Apps

Apps Overview

PayWeave Apps let you add MPP payment gating directly in your code. The SDK is split into a core library and framework-specific adapters that handle the protocol for you.

Architecture

Plain Text

@payweave/core            ← Base class, types, MPP charge logic
  ├── @payweave/express   ← Express middleware
  ├── @payweave/fastify   ← Fastify preHandler hook
  ├── @payweave/hono      ← Hono middleware (edge-compatible)
  └── @payweave/next      ← Next.js route handler wrapper

All adapters extend the core PayweaveBase class and follow the same pattern: create a Payweave instance with your credentials, then call .charge() to create framework-native middleware.

Creating an app

From the dashboard, go to Apps → Create App. You'll receive:

appId - Your public key identifier (e.g. app_cm5abc123def456), safe to include in code.

appSecret - Your secret key, prefixed with sk_test_ or sk_live_. Store it securely in environment variables.

Authentication

Pass both values when creating a Payweave instance:

TypeScript

import { Payweave } from '@payweave/hono'; // or express, next, fastify

const payweave = new Payweave(
  process.env.PAYWEAVE_APP_ID!,
  process.env.PAYWEAVE_APP_SECRET!
);

On the first charge request, the SDK authenticates with the PayWeave API using your secret key. If the secret is invalid, a 401 error is returned immediately. The secret prefix determines the mode: sk_test_ for test mode, sk_live_ for live.

Never expose secret keys in client-side code, public repositories, or logs. The secret is only shown once at creation. You can rotate it from Settings if compromised - secrets are hashed at rest.

Installation

Install the adapter for your framework (core is included as a dependency):

Terminal

npm install @payweave/express   # Express
npm install @payweave/hono      # Hono
npm install @payweave/next      # Next.js
npm install @payweave/fastify   # Fastify

Charge options

All adapters accept the same options in .charge():

Option	Type	Description
price	string \| (req) => string	Price per request in USD, e.g. '0.01'. Can be a function for dynamic pricing.
description	string	Human-readable endpoint description shown in 402 responses.
meta	Record<string, string>	Arbitrary key-value metadata attached to the payment record. Useful for agent discovery and analytics.

How charging works

When a request hits a route protected by payweave.charge():

1. The middleware calls the PayWeave platform API with the price, description, and any payment credential from the Authorization header.

2. No payment credential: Returns 402 Payment Required with a WWW-Authenticate header containing MPP pricing details.

3. The agent submits payment on Tempo and retries with Authorization: Payment <credential>.

4. Valid payment: PayWeave verifies the payment, adds a Payment-Receipt header, and calls your handler.

5. Invalid payment: Returns 402 with an error message.

Dynamic pricing

Pass a function instead of a string to compute price per request:

TypeScript

payweave.charge({
  price: (req) => req.body.premium ? '0.01' : '0.001',
  description: 'Search API',
})

The SDK retries platform calls up to 3 times with exponential backoff if the PayWeave API is temporarily unreachable.

Quickstart Express