Developers: ErgoPay for integrators
ErgoPay (EIP-20) lets a phone wallet take part without a browser extension. Kadia uses it twice: to learn the wallet’s address, and to have the wallet sign a transaction. On a Kadia site the request store is at /api/ergopay/testnet/v1/.
Getting the address
Section titled “Getting the address”POST connectwith{}. The answer is{sessionId, pollToken, url, expiresInSeconds}. A session lasts 300 seconds by default.- Show
ergopay://{host}{path}/connect/{sessionId}/#P2PK_ADDRESS#as a QR code, or as a link on the same phone. The wallet fills in its address and callsGET connect/{sessionId}/{address}. - Long-poll
GET connect-status/{pollToken}?wait=10(waitis 0 to 14 seconds) until it saysconnected. That answer comes once; after it, the session is gone.
This doesn’t prove the person owns the address. It only tells you where to look.
Signing
Section titled “Signing”-
Build. Ask the DEX service for the build with
ergoPay: true. It returns an EIP-19 reduced transaction,ergoPay.reducedTransactionBase64Url, and may add astoreTokenwithstoreTokenExpiresAt. Check the reduction against the build before showing it: its signing message must equal the build’ssigningMessageHex. dex-sdk’sassertErgoPayReductiondoes this. -
Choose a transport.
- Static, with no server:
ergopay:{base64url}, padded with=to a multiple of 4, which the Android wallet needs. Always used on the same phone. In a QR code, only while"ergopay:".length + ceil(bytes × 4/3)is at most 2,331. - Through the request store: anything larger.
- Static, with no server:
-
Store it with
POST requests. A JSON body is required (415 otherwise). There are two shapes:- Checked:
{reducedTx, txId, storeToken, storeTokenExpiresAt, message: "Kadia transaction"}, using only the build’s own token. - Unchecked:
{reducedTx, txId, unchecked: true}and nothing else. Use this for anything without a well-formed token from the build, including a transaction you built yourself. Never make up a token.
The answer is
{apiVersion: "1", data: {url: ".../requests/<id>"}}. Show it asergopay://plus that URL, which must be https and on the store’s origin. - Checked:
-
The wallet fetches it with a plain
GET requests/{id}, plain EIP-20 JSON:- checked:
{reducedTx, message: "Kadia transaction", messageSeverity: "INFORMATION"}; - unchecked: the message is “Built by this page, not checked by Kadia”, with severity
WARNING.
A stored request lasts 900 seconds by default.
- checked:
-
Learn that it was sent. Watch your node,
GET /transactions/unconfirmed/byTransactionId/{txId}thenGET /blockchain/transaction/byId/{txId}, every few seconds. When it appears, check it is the transaction you built: the same inputs, data inputs and outputs.
The store’s rules
Section titled “The store’s rules”reducedTxis unpadded base64url, at most 65,536 characters (413TOO_LARGE).txIdmust be the blake2b-256 of the signing message (400TX_ID_MISMATCH).- The same
txIdwith the same bytes gets the same URL; with different bytes it’s 409DUPLICATE_TX. - Token errors: none given is 403
UNBOUND_REQUEST, a wrong one is 403BAD_STORE_TOKEN, and an expired one is 403STORE_TOKEN_EXPIRED. A token is good for at most an hour; Kadia’s builds give 10 minutes. - The token is an HMAC-SHA256 under a secret the store shares with the DEX service, over
"kadia-ergopay-store-v1", the SHA-256 of the reduced transaction and the expiry. Without that secret, a store takes unchecked requests only. - Limits per client IP: 30 POSTs, 120 GETs, 10 connects and 120 polls a minute. The store is full at 1,000 requests (503
STORE_FULL). - A Kadia site forwards only these routes, checks the body’s shape, and allows only the title “Kadia transaction”.
Running it yourself
Section titled “Running it yourself”The request store is a small Python 3.11 standard-library service, run on loopback behind a proxy. Its public_base must be an https URL the phone wallet can reach. The page refuses plain http, localhost and another origin. Its README in kadia-dex covers the configuration and the shared secret.
Technical details
Sources: kadia-dex packages/kadia-ergopay-store/README.md (the request store) and packages/dex-sdk/src/ergopay.ts, at commit 908de0d (908de0db649a2904f3cc480fc9dbb0f92749a829); kadia-web packages/data/src/ergopay-sign.ts, packages/data/src/ergopay.ts, packages/app-kit/src/signing-deps.ts, and packages/serve/src/routes.mjs (what a Kadia site forwards), at 1586b24; docs/ui-safety-checklist.md.