payd · the http contract

what payd is, before any code

payd is self-custodial. A merchant gives it an extended PUBLIC key; payd works
out one receiving address per order from that key and watches the chain for
money arriving there.

It cannot sign, hold, move or return money. There is no balance, no payout and
no refund it can carry out for anybody. A refund in payd is a RECORD of a
transfer a person made from their own wallet.

Anything you write that assumes a balance, a payout, an automatic refund or a
"charge the customer" call is wrong about the product, not about the API.

the credential

One header:

    Authorization: Bearer payd_sk_...

The scheme is matched case-insensitively and a bare key with no scheme also
works. A key is payd_sk_ followed by 43 base64url characters.

Two scopes, and one distinction: taking money versus CHANGING WHERE MONEY GOES.

    write   orders, instructions, settlement, refunds. The default.
    admin   that, plus the wallet and the keys themselves.

A shop's checkout holds a write key. It issues invoices and settles them all
day and cannot repoint the wallet, which is the difference between a leaked key
costing a merchant their order history and costing them their income.

A third credential exists and is not a scope: the deployment key, out of
PAYMENTS_API_KEY, which is the only thing that may read across merchants. No
merchant key can be minted with it.

401 never says which credential failed. An unknown key, a revoked key and a
suspended merchant are one answer with no way to tell them apart.

404 never distinguishes gone from not-yours from not-a-route. Do not branch on
it and do not log it as a bug.

SERVER SIDE ONLY. The key is a bearer credential and belongs in an environment
variable, never in a browser and never in a file you commit.

A READY-MADE CLIENT THAT SETS THIS HEADER ships in the checkout, at
src/client.js, exported as ./client. It covers the operations an integration
performs, uses these operation ids as its method names, and answers what each
route answers. It is a convenience over this API and not a second contract: what
is promised is promised about the routes.

asking what this deployment can do

GET /health carries a capabilities array: sorted, opaque tokens naming
behaviour this deployment has. It is in front of the key check, so it is the one
question you can ask before you have been given a credential — which is exactly
when a connector needs to know what it is talking to.

BRANCH ON MEMBERSHIP AND NOTHING ELSE. Do not parse a token apart, do not order
your own copy differently, and do not read version or the database generation
for this purpose: one is a build number you would have to keep a table for, and
the other is a database fact VERSIONS.md deliberately leaves outside the promise.

    api.strict-json-body
        A non-empty body that is not one JSON object is a 400 on every /api route that reads a body.

    invoice.price-restrike
        A lapsed price is re-struck on invoice load if the ledgers read empty.

    orders.currency-refused
        An order in a currency this build cannot price is refused, not stored.

    orders.list-paged
        GET /api/orders pages the orders this key may read, newest first, with a cursor in next.

    orders.payments-bounded
        The order read bounds payments[] and publishes paymentsOmitted.

    orders.settlement-verdict
        GET /api/orders/:reference answers state, and settlement, outstanding and the required depth on the live instruction.

    payments.config-policy
        GET /api/payments/config answers policy: the depth per chain, tolerance, precision and EVM chain id this deployment uses.

    payments.outstanding-paged
        GET /api/payments/outstanding pages, with a cursor in next.

    webhooks.settlement-figures
        payment.settle-refused is delivered, and every body names the instruction, what arrived on chain, what is still outstanding and how far over a settlement ran.

THE RULE THESE ARE PUBLISHED UNDER, in four sentences. An adapter may assume that
every field named in a shape test is present and means what these documents say
it means. A field may be ADDED to a response in a minor release; nothing is
removed, renamed or re-typed except in a major one. A token published here is not
removed for two major releases, and an adapter that finds one absent must degrade
rather than guess what the deployment does. Anything no shape test holds is not
promised, however plainly it is written down.

the check that costs nothing

Four calls, on a real deployment, that cost nothing and prove your integration
is wired up.

    PAYD=https://your-deployment
    KEY=payd_sk_...

    # 0. May I, and can this shop be billed at all?
    curl -sS "$PAYD/api/merchant" -H "Authorization: Bearer $KEY"

    # 1. Register an order that costs nothing. A zero total is FREE, and free
    #    orders are registered already paid.
    curl -sS -X POST "$PAYD/api/orders" -H "Authorization: Bearer $KEY" \
      -H 'content-type: application/json' \
      -d '{"reference":"PAYD-CHECK-1","goodsCents":0,"shippingCents":0}'
    # 201 {"order":{"reference":"PAYD-CHECK-1","status":"paid","totalCents":0,
    #      "publicToken":"QrtKmvXbdLnpWfzJaHcEuSy", ...},
    #      "invoiceUrl":"$PAYD/i/QrtKmvXbdLnpWfzJaHcEuSy"}
    # invoiceUrl is the whole of what you send a buyer. It is the token above,
    # composed against this deployment's own origin, so it is a credential.

    # 2. Ask to bill it. A free order settles instead of issuing an address, so
    #    no address is worked out and nothing can be sent anywhere.
    curl -sS -X POST "$PAYD/api/orders/PAYD-CHECK-1/payment" \
      -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
      -d '{"rail":"BTC"}'
    # 200 {"order":{"status":"paid",...},"payment":null,"free":true}

    # 3. Read it back, and read the customer's own view of it.
    curl -sS "$PAYD/api/orders/PAYD-CHECK-1" -H "Authorization: Bearer $KEY"
    curl -sS "$PAYD/i/QrtKmvXbdLnpWfzJaHcEuSy/state"

    # 4. Prove the retry rule. This must answer 400, not 409, and it means
    #    ALREADY REGISTERED.
    curl -sS -X POST "$PAYD/api/orders" -H "Authorization: Bearer $KEY" \
      -H 'content-type: application/json' \
      -d '{"reference":"PAYD-CHECK-1","goodsCents":0,"shippingCents":0}'
    # 400 {"errors":{"reference":"Reference PAYD-CHECK-1 is already in use."}}

WHAT THIS PROVES: your key works and its scope is enough, your JSON reaches the
server, the order lifecycle is wired, and your retry handling reads a taken
reference correctly.

WHAT IT DOES NOT PROVE: address derivation, the rate feed, or settlement from
the chain — none of which happen on a free order. For those, set a wallet and
register an order for five cents on LTC: the instruction is real and carries a
real address, and if you never send anything it lapses when the payment window
ends — two hours by default — and costs nothing.

THIS IS NOT A TEST MODE AND THERE IS NO TEST MODE. PAYD-CHECK-1 is a real order
and will sit in that shop's invoices book for ever. Use a reference the merchant
will recognise later.

money

Fiat is INTEGER MINOR UNITS. goodsCents, shippingCents, totalCents,
amountCents, receivedCents, owedCents — all whole numbers of cents.

Crypto is an EXACT DECIMAL STRING. quotedAmount, chainAmount, assetAmount and
shortfallUnits are TEXT in the database and strings on the wire, and they are
compared as strings.

NEVER A FLOAT, in either direction. One ether is 10^18 wei, which is two orders
of magnitude past Number.MAX_SAFE_INTEGER, so a float quietly hands the customer
a number that is not the number they owe. Cents lose the same way, more slowly.

goodsCents: null is NOT 0. null means nobody has priced it yet and the order
sits in quote_requested with a null total. 0 means free, and a free order is
registered already paid — asking to bill it settles it instead of issuing an
address, so nothing is derived and nothing can be sent anywhere.

Amounts are quoted at the asset's ASKING precision rather than its full one, and
always rounded UP. Being over by one satoshi costs nothing; being short by one
never settles itself.

retries, and what stands in for an idempotency key

THERE IS NO IDEMPOTENCY-KEY HEADER AND NO REQUEST DE-DUPLICATION.

Your own order reference is the de-duplication. Send one on POST /api/orders,
and a repeat answers:

    400 {"errors":{"reference":"Reference PP-4821903 is already in use."}}

A retry after a timeout must read that as ALREADY REGISTERED and go and fetch
the order, not as a bad request. It is deliberately not a 409: a 409 would
invite a client to treat it as a conflict to resolve, when the correct handling
is to carry on.

Billing the same order twice on the same coin returns the SAME address, because
the derivation index is held per order per keyring. So an interrupted
POST /api/orders/:reference/payment is safe to repeat: it voids the outstanding
instruction and issues a new one at the same address — unless the chain has
already seen money against it, in which case it is refused.

Nothing else de-duplicates. Minting a key twice leaves two keys; adding a
webhook twice delivers everything twice; recording a refund twice records two
refunds.

every response object, field by field

Order

An order, staff side. What GET /api/orders/:reference returns under order.

CustomerOrder

The same order as a stranger holding the link may see it. An ALLOW list — a new column does not appear here until somebody decides it should.

Payment

A payment instruction, staff side. An instruction to a customer, never a movement of money — payd holds public keys and cannot send anything.

PaymentLeg

One ledger of one instruction, staff side. Two legs can share an address: ERC-20 and BEP-20 are two balances at one 0x….

CustomerPayment

What customerPayment() hands back, which is what every /api route returns under payment. A DENY list over Payment: note, derivationIndex, confirmedBy, shortfallUnits, slippageBps and merchantId are removed, and every leg loses its derivationIndex.

CustomerPaymentLeg

A leg with its derivationIndex removed. The index is a running count of the shop's orders, so two invoices a week apart would disclose their volume.

OrderPayment

What GET /api/orders/:reference returns under payment: CustomerPayment plus this deployment's verdict — the settlement shape, what is still owed, and how deep it has to be buried. The other four routes that answer payment still answer a plain CustomerPayment.

OrderPaymentLeg

A leg on the merchant's order read: CustomerPaymentLeg with the depth this deployment requires for that ledger. Per leg because the depths genuinely differ — Bitcoin settles at 1 and Tron at 19.

InvoicePayment

What a stranger holding the link sees under payment. CustomerPayment with id and orderId removed — both are AUTOINCREMENT counters shared by every merchant on the deployment — and the confirmation depth added.

InvoiceLeg

A customer-facing leg with its own confirmation depth. Per leg, not per instruction: Bitcoin settles at 1 and Tron at 19, and one number for both would be quoting the wrong chain at somebody.

InvoiceState

The whole of what GET /i/:token/state returns. No key. The token in the path is the entire authorisation.

TimelineEvent

One moment in an instruction's life. Append only, never revised, customer-safe by construction — there is nothing on it to strip.

Refund

A record that money was sent back. RECORDS ONLY — payd sends nothing and cannot: it holds extended public keys. A person made the transfer.

RefundPosition

What an order still owes. MIXED CASE, and the one shape in this API where that is true of a single response: the three figures are camelCase and payment is a raw payments row.

PaymentRow

A payments row exactly as SQLite returns it. Reached only through RefundPosition.payment. Listed because it is the one place an integration meets a payment in snake_case, and reading amountCents off it silently gives undefined.

Check

What POST /api/orders/:reference/paid found when it went and looked. A reading, never a decision — verdict is struck by the same function the sweep uses.

Policy

What THIS DEPLOYMENT decides about money, on GET /api/payments/config. The three lists beside it on that route are the CALLER's and depend on the keys the shop holds; this one is the same for everybody here and covers every asset the build knows.

ChainPolicy

One chain's settlement policy. Depth is per chain and not per asset: a token is buried by the same blocks the chain's own coin is.

AssetPolicy

One ledger's precision and dust allowance. The dust is absolute and never a percentage. A shop that sets a slippage adds its own percentage on top, per invoice — that is on the instruction (slippageBps), not here, because it is the shop's and not the deployment's.

MerchantWhoami

Everything a shop needs to know about its own setup, in one call. Step zero of any integration.

Key

A merchant key as POST /api/merchant/keys returns it under record. snake_case: it is a SQL RETURNING row and never passes through a shape function.

KeyListing

A key as GET /api/merchant/keys lists it. Also snake_case, and NOT the same field set as Key — there is no merchant_id and there are two timestamps more.

Wallet

One keyring this shop is billed on. The extended key is PUBLIC and is returned in full, on purpose: it derives addresses and cannot sign.

Address

One address this shop has been ISSUED, with everything billed against it. Issued, not derived: an index is allocated before an address is committed, so the sequence has holes and nextIndex is an upper bound rather than a count.

Webhook

A delivery endpoint. snake_case — the row is returned as SQLite hands it over.

Delivery

One attempt to tell you something. snake_case, for the same reason.

WebhookBody

What arrives at your endpoint. Signed with payd-signature: t=<unix>,v1=<hex>, HMAC-SHA256 over ${t}.${rawBody}. A doorbell, not the truth — reconcile against GET /api/orders/<reference>.

WebhookBodyOrder

The order on a webhook body: the reference you registered, where the order stands now, and what it was for. Enough to find it again and nothing more — a body travels to a URL that ends up in logs.

WebhookBodyPayment

The payment on a webhook body: which instruction, what was asked, and what the reading that caused this event actually held. Every figure is copied from the event, never recomputed, and a figure nobody measured is null rather than zero.

Health

Whether this deployment is alive and watching the chain. No key. Nothing here counts anything, names anybody, or moves when a merchant's customers do.

FieldErrors

The field-validation 400 body. The ONLY error shape with a plural: everything else, including the 400 for a body that is not one JSON object, is { "error": "<sentence>" }.

every operation

service

merchant

wallet

webhooks

orders

billing

refunds

payments

invoice

the closed sets

which status may become which

Being listed here is not permission on its own. placed and quoted reach paid directly only for an order whose final total is zero, and that guard is enforced separately — a table saying a move is legal beside a service refusing it would read as a bug rather than as the rule it is.

rails — what a customer picks

assets — what is actually watched

A rail is a ticker and an asset is a ledger. Sending asset narrows an instruction to one network; sending rail alone bills the first network the order offers for that coin, and the invoice does not let the customer move it. To let the customer pick, leave the order unbilled: the invoice offers its coins and networks before any address exists. The network column is the one to show them — "USDT" on its own is four different transfers.

keyrings — what a merchant exports

settlement, and what never settles itself

Automated promotion is EXACT-OR-OVER AND BURIED. An instruction settles by
itself only when the full quoted amount is visible on the ledger it was issued
for and it is confirmed deeply enough for that chain. Bitcoin wants 1
confirmation and Tron wants 19, which is why the required depth is published per
leg rather than per instruction.

NOTHING SETTLES A PAYMENT THAT ARRIVED SHORT. Not eventually, not after any
number of confirmations, not after any amount of waiting. It goes to the state
short and stays there until a person calls
POST /api/payments/:id/settle-short with a note saying why. That is the single
most important sentence in this document for anybody building a checkout.

The sweep only ever PROMOTES. It never marks a payment short, never cancels,
never reverses and never refunds.

OVER-PAYMENT settles. The order is paid; what to do about the excess is a
conversation between a shop and its customer, and payd records the figures for
it and takes no view.

LATE MONEY STILL LANDS. Expiry releases the hold on the goods; it does not
refuse money. The address stays ours, an expired order can be reinstated or paid
outright, and payd will not turn away a transfer because a clock ran out.

A SUSPENDED MERCHANT is a door being closed, not a payment being refused. Money
already on its way to an address they were billed on still arrives, is still
matched, and still settles.

webhooks

THE WEBHOOK IS A DOORBELL, NOT THE TRUTH.

Five of the six events are delivered: payment.settled, payment.settle-refused, payment.short, payment.expired, order.status.
payment.sighted is deliberately not among them — it fires every time a figure
moves on chain, which is useful to staff watching a screen and is noise to a
server that only cares whether it may ship. AN EVENT YOU DO NOT RECOGNISE MUST BE
ANSWERED 2xx AND IGNORED: a handler that refuses an unfamiliar name fails its
ladder, and enough of that trips the breaker and stops your shop being told about
settlements at all.

Each delivery carries:

    payd-signature: t=<unix>,v1=<hex>
    payd-delivery:  <id>
    payd-event:     <name>

The hex is HMAC-SHA256 over ${t}.${rawBody} with the secret you were shown
once when you added the endpoint. Verify it over the RAW bytes, before parsing,
and refuse anything with a timestamp older than a few minutes.

IF YOUR HANDLER RUNS OFF DENO, DO NOT WRITE THAT CHECK YOURSELF. verifyWebhook
in src/client.js, exported as ./client, is the same check built on WebCrypto
rather than node:crypto, so it runs on Node, on Bun and on an edge runtime where
node:crypto is not there. It is async because crypto.subtle is, it takes the raw
body, and it shares its header parse, its age guard and its signed material with
the function that signs here — so the two cannot drift apart. It exports no
signer, deliberately: something that mints one of these inside your own process
is a forgery tool aimed at your own handler.

ONE BODY SHAPE FOR EVERY EVENT, so you parse it once and branch on event:

    { event, at, order: { reference, status, totalCents, currency },
      payment: { id, rail, asset, amountCents, receivedCents, status,
                 chainAmount, outstanding, overCents } | null }

A field the event has nothing to say about is NULL rather than absent. Which of
them are populated, per event:

    payment.settled         chainAmount is what the chain held; overCents is how
                            far past the ask it ran, 0 on the nose, and null on a
                            confirmation made by hand — an accepted short
                            included, which carries a chainAmount all the same.
                            outstanding is null: nothing is owed.
    payment.settle-refused  chainAmount is what arrived. MONEY EXISTS ON CHAIN
                            THAT THIS ORDER WILL NOT ACCEPT. Do not treat it as
                            informational: page a person, reconcile against
                            GET /api/orders/<reference>, and decide whether to
                            confirm it by hand or return it. Neither the address
                            nor the reason travels — the reason is in the
                            deployment's own log. Delivered ONCE per instruction
                            per endpoint FOR EACH FIGURE it refuses, because the
                            sweep refuses the same money again on every pass until
                            somebody acts: one page for that reading, and another
                            if chainAmount MOVES because more money landed on the
                            same address.
    payment.short           chainAmount is what arrived and outstanding is what is
                            still missing, both exact decimal strings in the
                            asset's own units. Delivered again whenever the figure
                            MOVES, so a customer topping up is visible. Nothing
                            settles until a person decides.
    payment.expired         the hold lapsed; payment is null and the instruction
                            is still live, so money in flight still lands.
    order.status            a settlement, or a status change a caller asked for;
                            payment is null.

COMPARE THE DECIMAL STRINGS, NEVER PARSE THEM. chainAmount and
outstanding are exact decimals in the asset's own units — one ether is 10^18
wei, well past what a float can hold — and amountCents, receivedCents and
overCents are whole fiat minor units.

DELIVERY IS AT LEAST ONCE AND CAN FAIL ENTIRELY. The ladder is
10, 30, 90, 300, 900, 2700 seconds — 6 attempts over
about 67 minutes —
and then it is given up on. An endpoint that fails five deliveries with nothing
accepted in between is disabled by a breaker until somebody enables it again.

ORDERING IS NOT GUARANTEED. The queue is drained oldest first in bounded
parallel, and a retry lands up to twenty-odd minutes behind whatever was queued
after it, so a payment.settled can arrive before the payment.short that
preceded it. Decide from the body and from the order read, never from arrival
order.

A 3xx IS A FAILURE AND IS NEVER FOLLOWED. Register the final URL. A redirect goes
through the same retry ladder as a 500 and counts towards the breaker like any
other failure — following one would mean the host checked at registration is not
the host that receives the body.

WHERE YOUR ENDPOINT POINTS IS CHECKED AGAIN BEFORE EVERY DELIVERY. Its host is
resolved here, for A and AAAA, immediately before the request, and every answer
must be a public address: one private record among several is a refusal rather
than a preference, and a name that answers nothing at all is refused too. Such a
delivery is never sent — it fails the attempt, takes the same ladder as a 500 and
counts towards the breaker. Two things follow for you. The lookup is DNS proper,
with no /etc/hosts and no search domains, so an endpoint that resolves only
inside your network is not deliverable to. And this NARROWS rebinding rather than
closing it: fetch resolves the name a second time and cannot be pinned to what
was checked, so the window is milliseconds rather than the hours between
registering an endpoint and being delivered to.

payd-delivery IS NOT THE DE-DUPLICATION KEY, whatever an older copy of this
paragraph told you. One event produces ONE payload, and that same payload is
queued once per live endpoint — so a shop with two endpoints pointed at one
handler receives two deliveries carrying identical bytes, at included, under
two different delivery ids. That header tells the 6
attempts of ONE delivery apart, and nothing else.

THE SIGNATURE IS NOT A DE-DUPLICATION KEY EITHER. t is when that attempt was
sent, so the six attempts of one delivery carry six different
payd-signature values over identical bytes.

De-duplicate on what the
body says: the order's reference, the event and order.status, beside
your own record of whether you have already shipped — which is the fact that
actually decides it.

THAT KEY IS THE SHIP DECISION, NOT AN INGRESS FILTER. payment.short and
payment.settle-refused are sent AGAIN precisely when the figure moved, and
both sends carry the same reference, the same event and the same
order.status — so a receiver that drops the second one throws away the
top-up, or the second arrival on money nobody can settle, which is the whole
reason those two are re-sent. Key those two on payment.id and
chainAmount as well.

And RECONCILE against GET /api/orders/<reference> rather than trusting that
anything arrived. A checkout whose only source of truth is a webhook is a
checkout that loses an order the first time your host restarts during a deploy.

errors

Two shapes, and only two.

    400  {"errors": {"<field>": "<sentence>"}}     field validation
    any  {"error": "<sentence>"}                   everything else

One refusal also carries a code beside its sentence, for a host to branch on
without matching words: {"error": "<sentence>", "code": "plan_ceiling"} is the
409 POST /api/orders/:reference/payment answers when the shop's plan ceiling
refuses a new invoice. No other refusal carries a code, so do not wait for one.

A BODY THAT IS NOT ONE JSON OBJECT is refused on every route that reads a body,
after the key, the scope and the resource are checked and before anything is
done. It is the second shape, at 400:

    400  {"error": "The request body is not valid JSON."}
    400  {"error": "The request body must be a JSON object."}

So at 400, read error before errors. An empty body is not refused: zero bytes, or
nothing but whitespace, is read as no body, as it always was.

The sentences are stable. VERSIONS.md makes them a promise because host
applications read them back, and this document generates them from the modules
that emit them, so a sentence that changed would change here too.

Status codes that mean something specific here:

    400  a field was wrong — INCLUDING a reference already in use, which is
         success for a retry after a timeout and is deliberately not a 409
    401  the credential did not resolve. Which one, and why, is not said
    403  the key is real and is the wrong scope. Only on the admin routes,
         where you already know your own account exists
    404  gone, not yours, or not a route. Never distinguished
    409  the request was well formed and the state forbids it
    429  a rate limit. Honour Retry-After
    500  {"error": "Something went wrong."} and nothing else, ever

Nothing in an error body names another merchant, an address you were not given,
a key, a token or a secret. A refusal says what was NOT done and does not
explain how to get closer.

rate limits

Three routes are limited, all keyed on the MERCHANT and not on the path:

    POST /api/orders/:reference/payment          20 per 60s
    POST /api/orders/:reference/payment/requote  15 per 60s
    POST /api/orders/:reference/paid             6 per 60s

The last is tightest because each call is an outbound request to a public
explorer.

Keying on the merchant rather than on the path is load-bearing: the path on all
three carries the order reference, so a per-path key would have given every
reference its own budget and let one caller multiply their own limit by using
more references.

The invoice routes are limited by TOKEN (60/minute, once the token resolves) and
by IP on MISSES only (20/minute), so a shop's own customers never meet the
second however many of them share an office address.

Every 429 sets Retry-After. Honour it.

make me an mcp server

THERE IS NO MCP SERVER HERE, and no tool manifest. What there is, is enough to
generate one: /openapi.json carries four extensions per operation that plain
OpenAPI has no vocabulary for, and they are exactly what a bridge needs.

    x-payd-scope          which credential the operation wants
    x-payd-effect         what it does in one clause, in the product's terms
    x-payd-safe-to-retry  whether repeating it after a timeout is safe
    x-payd-idempotent     whether repeating it changes anything

Generate read-only tools from every GET. Mark these DESTRUCTIVE and require
confirmation: revokeKey, removeWebhook, setWallet, recordRefund, settleShort,
confirmPayment, setOrderStatus. Each either destroys a credential, decides where
future money lands, or settles an order on a person's word.

Mark issuePayment NEITHER read-only NOR destructive: it moves no money and
cannot, but it does void an outstanding instruction, so a confirmation step is
cheap insurance and an automatic retry is not.

And give the agent GET /api/merchant first. Every other decision — which rails
to offer, whether this shop can be billed at all, whether the key can change the
wallet — is answered there in one request.

what is not documented, and not to be scripted

/app is the merchant's own browser portal: form-encoded HTML behind a session
cookie, with CSRF on every POST and a per-route field allow-list that answers 400
for anything unexpected. It is explicitly OUTSIDE the compatibility promise in
VERSIONS.md and its markup may change in a patch release.

Do not script it. Everything it does that a program should do is on /api, and
the credential for that is a key rather than a person's password.

what this page cannot tell you

Four things this file cannot tell you, because they are facts about a running
deployment rather than about payd:

    Whether the chain is being watched at all. startChainWatch is opt-in at
    boot, and with it off nothing settles by itself. Ask GET /health —
    chain.watching, and chain.stale, which is the one to alarm on.

    Whether the rate feed is alive. Ask GET /health — rates.fresh and
    rates.ageSeconds, both null when nothing has ever been priced.

    Which coins THIS shop can be billed on. That is a property of the extended
    keys this merchant has configured, not of payd. Ask
    GET /api/payments/config, and offer only the rails it returns.

    What this deployment is called or where it lives. Every link in these
    documents is relative on purpose. The base URL for /api and /i
    is https://app.payd.sh; everything else resolves against where you fetched this.