PPOps

Self-hosted PayIn operations for private USDC on Arbitrum.

Your backend creates a payment request. A separate RAILGUN wallet pays it. PPOps observes the merchant wallet through a viewing key and sends your backend a signed webhook when the payment is finalized, spendable and matched.

PPOps never holds the merchant's spending keys. Run one instance per receiver, network and token.

PayIn means one incoming payment: a signed request, execution in a separate payer wallet, view-only detection, validation, matching and merchant notification. See the PayIn model and checkout. Payout is roadmap only.

From this source checkout, with Node.js 24:

npm ci
npm run demo

Open http://127.0.0.1:8788/shop/. Create an order, open its payment request, click Simulate payment, then return to the shop to inspect fulfillment. No wallet, provider accounts or funds are required. Temporary demo data is removed when you stop the process.

See the demo guide for details on what it exercises.

The merchant needs a shareable RAILGUN viewing key, independently operated Arbitrum RPC endpoints (at least two; three recommended), a compatible PPOI endpoint and persistent storage. Your backend keeps the API token and verifies incoming webhooks.

The payer needs private native USDC already available to spend, plus enough balance for the payment and fee. Public EVM transfers do not pay a PPOps request. The included reference payer is a command-line tool for developers and testing.

The supported merchant profile is Arbitrum One, native USDC, 6 decimals. PPOps includes no swaps, refunds, fiat conversion, hosted payment processing or automatic wallet funding.

1. Your backend sends POST /v1/intents with a stable idempotency key, integer amount and future expiry. Persist the returned intent ID with your order.
2. Show the payer the returned checkoutPath on your public payment origin. Keep the merchant API token on your backend.
3. Verify the raw-body webhook signature and deduplicate the event ID in the same database transaction as fulfillment. Apply your policy for late payments.

The runnable merchant example demonstrates that flow, including retries and durable deduplication. Optional TypeScript HTTP helpers are exported at ppops/client from the built source package.

The current release is v0.1.0-beta.3: browser-side request verification, a local request QR, clearer payment progress and reference-payer readiness. It retains the beta.2 demo, doctor/status, TypeScript helpers and OpenAPI. Wallet-native handoff remains unvalidated; the checkout does not connect a wallet.

Verification reports and benchmarks are documented in the evidence index.

The project is distributed as source and a merchant Docker image; it is not published on npm. See deployment for the difference between building this checkout and using a published image.

npm run typecheck
npm test
npm run build
npm run verify

The payer is an independent package. Only payer contributors and full-release verification need npm run payer:install followed by npm run verify:all.

src/                 daemon, HTTP client helpers, isolated demo and merchant example
examples/            runnable merchant integration
config/              deployment examples
docs/                task guides, reference and review evidence
test/                automated checks
tools/ppops-payer/    separate payer package and spending runtime
scripts/             maintainer verification tools
skills/ppops/        agent workflow referring to the same product documentation
artifacts/           signed/redacted historical evidence

Read security guidance before operating real value. Report vulnerabilities privately as described in SECURITY.md.

Apache-2.0. See LICENSE.