Required reading

Your First PayPort Node

First Build It. Then Pay It.

Your first goal inside PayPort Labs is simple:

> Build your own PayPort Node, deploy it, and register it in District Zero.

You do not need to understand blockchain settlement before you can build your first Node.

You do not need to claim one of Town #1's commercial opportunities.

You do not need to build a complete SaaS product.

We'll learn one layer at a time.

Who hosts your Node?

You do. PayPort Labs does not host the Builder's Node for them.

Whether you are practicing in District Zero or claiming one of Town #1's commercial opportunities, you must deploy your own instance of the Node on infrastructure outside the PayPort Labs application.

That infrastructure may be:

  • Railway (recommended beginner path);
  • Render or another suitable application host;
  • your own VPS/VM;
  • another public hosting environment that provides a reachable HTTPS endpoint.

You do not need to buy a VM.

You do need to operate your own deployment and give Labs that deployment's public HTTPS base URL.

Builder's Node code
        ↓
Builder deploys their own instance
        ↓
Railway / Builder VM / other public host
        ↓
Hosting environment provides public HTTPS URL
        ↓
Builder registers that URL with PayPort Labs
        ↓
Labs verifies /health + agent.json + wallet ownership

Labs Reference Demos (Practice Echo on Labs :8142, Demo HVAC on :8141, monorepo district examples) are for looking and learning — not your deployment. Do not register those URLs as your Node.

The Two-Part Journey

Your first Node journey has two stages.

PART ONE

BUILD
↓
RUN LOCALLY
↓
CONFIGURE WALLET
↓
DEPLOY
↓
REGISTER
↓
MY NODES

Then:

PART TWO

HTTP 402
↓
PAYMENT CHALLENGE
↓
BASE SEPOLIA tUSDC
↓
REAL TRANSFER
↓
TX HASH
↓
VERIFIED SETTLEMENT

In Part One, payment settlement stays simulated (PAYMENT_MODE=mock).

In Part Two, you'll deliberately turn on testnet settlement (PAYMENT_MODE=base_sepolia) and learn what changes.

Part One — Build and Register Your First Node

Your Mission

You are going to create a simple Practice Echo Node.

An Echo service does one thing:

Input:
Hello PayPort

↓

Output:
Hello PayPort

The business logic is intentionally simple.

That lets us focus on the important parts:

  • the Merchant Template;
  • running a FastAPI Node;
  • understanding /health;
  • understanding agent.json;
  • seeing an HTTP 402 payment challenge;
  • connecting your Builder Wallet;
  • deploying your Node;
  • obtaining its public URL;
  • registering it with PayPort Labs.

When you're finished, your Node will appear in My Nodes.

Hands-on setup (where to type commands, what each one means, how to know it worked): Building Your First Node.

This page is the journey map so you always know *why* each step exists — especially what URL Labs asks for at claim time.

Step 1 — Create Your Own Repo From the Merchant Template

Builders do not clone the PayPort Labs monorepo.

Builders start with the public Merchant Template — then make their own GitHub repository from it:

  1. Open payport-merchant-template
  2. Click Use this template → Create a new repository
  3. Name it something yours (e.g. my-practice-echo)
  4. Clone your new repository (not the PayPort master template forever)
PayPort Merchant Template (official)
        ↓
Use this template
        ↓
Your own GitHub repository
        ↓
git clone YOUR_REPO
        ↓
build Practice Echo → run locally → deploy YOUR repo

Railway (and other hosts) should deploy your repository, not treat the official PayPort template repo as your project.

Do not start typing git clone / pip / uvicorn until you know which computer is running the command. Follow the explained walkthrough: Building Your First Node.

The Merchant Template contains the common PayPort plumbing your Node needs.

Your job is to implement the service.

For your first exercise, that service is Practice Echo (District Zero), not a commercial dental franchise yet.

Think of the Merchant Template as the foundation of a building.

You aren't rebuilding the foundation every time you create a business.

You're deciding what happens inside the building.

Golden rule: edit app/service.py and your private .env. Do not edit app/main.py or app/core/security.py — those enforce 402 and the manifest.

District folders under the Labs monorepo are Reference Node examples. They are for looking, not cloning as your Builder project.

Step 2 — Understand What You're Building

Every PayPort Node exposes a familiar surface.

At minimum, you'll encounter:

GET /health

GET /.well-known/agent.json

POST /v1/<service>

For Practice Echo, your paid business route is an Echo endpoint (for example POST /v1/echo).

The exact service logic is less important than understanding the pattern.

Step 3 — Run Your Node Locally

Before putting your Node on the internet, run it on your own computer (or on a VM you operate — still private until you expose HTTPS publicly).

Where? In a terminal on that machine — explained command-by-command in Building Your First Node (venv, .env, uvicorn, success checks).

Why locally first? So you can prove /health, agent.json, and 402 work before anyone on the internet depends on your URL.

When the server is running, test:

GET /health

A healthy response tells you:

> The application is running and PayPort Labs will be able to check its health later.

Next inspect:

GET /.well-known/agent.json

This is your Node's public manifest.

It tells other software what your service is, how it behaves, and where payments belong (recipient_wallet).

Remember: 127.0.0.1 / localhost is for testing only. It is not the URL you register with Labs.

Step 4 — See Your First 402

Call the paid Echo route without providing payment proof.

Your Node should respond:

HTTP 402

That does not mean something broke.

It means:

> This is a paid service. Payment authorization is required before the service performs the paid action.

This is one of the central ideas in the PayPort Protocol.

For now, we are only learning the flow.

We are not moving Base Sepolia tUSDC yet.

Keep:

PAYMENT_MODE=mock
ENVIRONMENT=village

Step 5 — Connect Your Builder Wallet to Your Node

Every Builder Node has an owner.

Your Node publishes a:

recipient_wallet

inside agent.json.

That wallet must match the Builder Wallet you use when registering the Node with PayPort Labs (SIWE session).

In the Merchant Template, set your wallet in .env as:

DEVELOPER_WALLET_ADDRESS=0xYourBuilderWallet

That is the canonical Merchant Template variable. It becomes agent.json recipient_wallet.

Builder triangle (must match):

SIWE wallet = DEVELOPER_WALLET_ADDRESS = agent.json recipient_wallet

Optional compatibility alias in the template only: PAYMENT_RECEIVER_WALLET → DEVELOPER_WALLET_ADDRESS. Builders should set DEVELOPER_WALLET_ADDRESS.

Labs-owned Reference Nodes in the monorepo may use MERCHANT_RECIPIENT — that is internal/reference configuration, not what you put in the Merchant Template.

Conceptually:

Your Builder Wallet
        ↓
Node environment configuration
        ↓
agent.json recipient_wallet
        ↓
PayPort Labs registration
        ↓
SIWE ownership signature
        ↓
Wallets match
        ↓
Ownership accepted

This prevents one Builder from taking somebody else's deployed Node and registering it as their own.

Keep your Node in:

PAYMENT_MODE=mock

for Part One.

In mock mode, payment authorization can be demonstrated without moving Base Sepolia tUSDC (authorization_verified=true, payment_verified=false, settlement_mode=mock).

Step 6 — Deploy Your Node (you host it)

So far, your Node has been running only on your own computer.

PayPort Labs does not spin up your Node when you register.

PayPort Labs cannot register a Node that exists only on your laptop, and it does not host the Builder's application for them.

You deploy your Merchant Template instance to infrastructure you operate:

  • Railway — recommended first path for beginners;
  • Render / Fly / similar app hosts;
  • your own VPS/VM;
  • any compatible public host with HTTPS.

The requirement is not “must own a VPS.”

The requirement is: operate your own deployed Node and obtain its public HTTPS base URL.

After deployment, your hosting provider gives your application a public HTTPS address similar to:

https://my-practice-echo.up.railway.app

You do not invent this URL.

PayPort Labs does not give you this URL.

Your hosting provider / environment gives it to you after your application is deployed.

Set MERCHANT_BASE_URL to that same public HTTPS base URL on the host.

This Is Your Node URL

This distinction is important.

If your hosting provider gives you:

https://my-practice-echo.up.railway.app

then this:

https://my-practice-echo.up.railway.app

is your Node's base URL.

You can test:

https://my-practice-echo.up.railway.app/health

and:

https://my-practice-echo.up.railway.app/.well-known/agent.json

But when PayPort Labs asks for:

> Live node HTTPS URL / Your deployed Node URL

you enter only:

https://my-practice-echo.up.railway.app

Do not enter:

  • /health or /.well-known/agent.json paths
  • localhost / 127.0.0.1
  • the Labs-hosted Practice Echo reference (:8142) or HVAC reference (:8141)

Those Labs hosts are reference demos — not claim targets.

You register the Node you deployed.

Step 7 — Verify Before Registering

Before returning to PayPort Labs, confirm:

Health

Your public /health responds successfully.

Manifest

Your public /.well-known/agent.json loads successfully.

Wallet

The recipient_wallet in your manifest matches your Builder Wallet.

Payment Mode

For this first exercise:

PAYMENT_MODE=mock

Step 8 — Register in District Zero

District Zero uses the same deployment-and-registration model as commercial Town #1:

Builder builds Practice Echo
        ↓
Builder deploys their own Echo instance (Railway / VM / other host)
        ↓
Gets their own public HTTPS URL
        ↓
Registers that URL
        ↓
PRACTICE Node appears in My Nodes

Labs does not host your D0 Node. The PRACTICE seat is inventory/lifecycle only.

Return to PayPort Labs:

  1. Open District Zero
  2. Choose Practice Echo
  3. Open Register / claim
  4. Paste the public HTTPS base URL your hosting provider gave you
  5. Sign the ownership message with the same Builder Wallet

PayPort Labs will check:

Is the Node reachable?
↓
Does /health respond?
↓
Does agent.json exist?
↓
Does recipient_wallet match your Builder Wallet?
↓
Can you sign the ownership message?

Registration itself does not settle a payment. It is identity + reachability + ownership.

If the checks pass, your Practice Node is registered.

District Zero differs from commercial only in inventory/lifecycle:

  • PRACTICE does not consume one of the 54 commercial seats;
  • PRACTICE does not count toward commercial node quota;
  • PRACTICE uses Reset Practice rather than commercial Release / reclamation.

> District Zero does not mean Labs hosts your software. You still deploy your own instance.

Step 9 — Open My Nodes

After registration, open My Nodes.

Your Practice Echo should appear there.

You have now completed something important.

You didn't simply read about a PayPort Node.

You:

  • created one;
  • ran it;
  • inspected it;
  • deployed it;
  • connected your wallet;
  • obtained its public URL;
  • proved ownership;
  • registered it with PayPort Labs.

That's your first Node.

When you're ready for the next practice exercise, use Reset Practice, then try HVAC Dispatch (a Node that consumes the Weather Anchor).

What About Payment?

Your Node already behaves like a paid service.

It can return HTTP 402.

PayPort Labs may probe the unpaid paid-route (crawler expects 402).

The Village Buyer Bot may perform simulated purchases against ONLINE nodes.

But because your Node is still using:

PAYMENT_MODE=mock

the normal Village exercise does not verify an on-chain Base Sepolia USDC payment.

You may see:

authorization_verified=true
payment_verified=false
settlement_mode=mock

That is intentional.

First we learned how to build and operate the Node.

Now we're ready to change one layer.

Part Two — Settle Your First Real Test Payment

Your Next Mission

You already have a working Node.

We're not rebuilding it.

Now you'll learn the difference between:

payment authorization

and:

payment settlement.

In Part One:

PAYMENT_MODE=mock

The protocol flow was demonstrated without verifying an on-chain payment.

In Part Two, you'll deliberately enable:

PAYMENT_MODE=base_sepolia

and complete a real testnet tUSDC transfer (with a valid tx_hash).

Authorization Is Not Settlement

This distinction is fundamental to PayPort Labs.

A wallet signature can prove that somebody authorized an action.

It does not prove that money moved.

In mock mode, PayPort Labs can demonstrate authorization and protocol behavior without claiming that a blockchain settlement occurred.

A verified Base Sepolia settlement requires actual transaction evidence.

What Changes in Base Sepolia Mode?

Your business logic does not change.

Your Echo service is still Echo.

Your endpoints remain familiar.

What changes is payment verification:

Buyer requests Echo
        ↓
HTTP 402
        ↓
Payment challenge
        ↓
Buyer sends Base Sepolia tUSDC
        ↓
Blockchain transaction
        ↓
tx_hash
        ↓
Payment proof
        ↓
Node verifies settlement
        ↓
Paid service executes

This is the same business interaction with real testnet settlement behind it.

The Labs Village Buyer Bot sends mock proofs (tx_hash empty). A base_sepolia node expects a real transfer — so Part Two is a deliberate exercise you drive with a testnet buyer flow, not something that happens accidentally after District Zero register.

Builder Fuel

Your Builder Wallet may receive testnet resources through Builder Fuel.

These are for learning and testing.

Base Sepolia tUSDC is testnet value — not production USDC.

Treat the testnet transaction seriously: the architecture is the same kind used when real settlement is eventually enabled.

Switch Payment Mode Deliberately

Only after your mock-mode Node is working should you change:

PAYMENT_MODE=mock

to:

PAYMENT_MODE=base_sepolia

Redeploy so the public Node picks up the change.

Do not treat production-style settlement as something that happens accidentally.

Complete the Payment

A Base Sepolia payment proof requires transaction evidence.

Unlike the mock exercise, a real settlement path requires a valid:

tx_hash

The Node uses that evidence to determine whether payment actually occurred.

A signature alone is not enough.

Verify the Result

After successful settlement, inspect the resulting payment information.

MOCK

authorization_verified=true
payment_verified=false
settlement_mode=mock

BASE SEPOLIA (verified)

payment_verified=true
settlement_mode=base_sepolia
tx_hash=<transaction>

You have now seen both sides of the PayPort Protocol.

What You Just Learned

You started with no deployed Node.

Now you understand the complete progression:

Business logic
↓
Merchant Template
↓
Local Node
↓
HTTP 402
↓
Builder Wallet
↓
Public deployment
↓
Public HTTPS URL
↓
District Zero registration
↓
My Nodes
↓
Mock settlement
↓
Base Sepolia settlement
↓
Verified transaction

That distinction matters.

You did not begin by learning blockchain.

You began by learning how to build a software service.

Then you learned how that software service can request and verify payment.

Ready for Town #1

District Zero was your rehearsal.

Town #1 contains a limited number of commercial opportunities (Wave 1 opens 18 of 54 seats).

Commercial claim uses the same host-your-own-Node pattern:

Builder chooses one of the 18 available opportunities
        ↓
Builder builds their own implementation
        ↓
Builder deploys their own Node (Railway / VM / other host)
        ↓
Gets their own public HTTPS URL
        ↓
Registers that URL
        ↓
COMMERCIAL seat becomes CLAIMED

The commercial seat is an inventory opportunity in PayPort Village.

It is not a hosted application instance supplied by Labs.

Claiming one of the 18 does not mean PayPort Labs spins up the software for you.

The registration mechanics should now feel familiar:

Build
↓
Configure
↓
Deploy (you host)
↓
Get your public URL
↓
Register
↓
Operate

You should no longer be wondering:

> "What URL goes in this box?"

You created it.

You deployed it (on Railway, your VM, or another host).

You tested it.

And now you know exactly what it represents.

Completion Check

Before moving on to a commercial opportunity, you should be able to answer yes to each question:

  • [ ] I deploy my own Node — Labs does not host it for me (D0 or commercial).
  • [ ] I created my own GitHub repo via Use this template (not forever cloning the official template as my project).
  • [ ] I set DEVELOPER_WALLET_ADDRESS (Merchant Template) — not Labs MERCHANT_RECIPIENT.
  • [ ] I understand the difference between the Merchant Template and a Reference Node.
  • [ ] I have run my own Practice Echo locally.
  • [ ] I have inspected /health.
  • [ ] I have inspected /.well-known/agent.json.
  • [ ] I have seen an HTTP 402 response from my paid endpoint.
  • [ ] I understand which wallet appears as my Node's recipient_wallet.
  • [ ] I deployed my own Node to a public host I operate (Railway, my VM, or compatible host).
  • [ ] I know where my public HTTPS Node URL came from (my hosting provider — not Labs).
  • [ ] I registered my Node in District Zero (not the Labs :8142 reference).
  • [ ] My Practice Node appeared in My Nodes.
  • [ ] I understand the difference between mock authorization and verified settlement.
  • [ ] I understand that Base Sepolia settlement is a separate deliberate exercise.
  • [ ] I understand a commercial seat is inventory, not a Labs-hosted app.

First learn to build and register a Node. Then learn to settle a real payment.

Next