Skip to content

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/.

  1. POST connect with {}. The answer is {sessionId, pollToken, url, expiresInSeconds}. A session lasts 300 seconds by default.
  2. 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 calls GET connect/{sessionId}/{address}.
  3. Long-poll GET connect-status/{pollToken}?wait=10 (wait is 0 to 14 seconds) until it says connected. 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.

  1. Build. Ask the DEX service for the build with ergoPay: true. It returns an EIP-19 reduced transaction, ergoPay.reducedTransactionBase64Url, and may add a storeToken with storeTokenExpiresAt. Check the reduction against the build before showing it: its signing message must equal the build’s signingMessageHex. dex-sdk’s assertErgoPayReduction does this.

  2. 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.
  3. 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 as ergopay:// plus that URL, which must be https and on the store’s origin.

  4. 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.

  5. Learn that it was sent. Watch your node, GET /transactions/unconfirmed/byTransactionId/{txId} then GET /blockchain/transaction/byId/{txId}, every few seconds. When it appears, check it is the transaction you built: the same inputs, data inputs and outputs.

  • reducedTx is unpadded base64url, at most 65,536 characters (413 TOO_LARGE). txId must be the blake2b-256 of the signing message (400 TX_ID_MISMATCH).
  • The same txId with the same bytes gets the same URL; with different bytes it’s 409 DUPLICATE_TX.
  • Token errors: none given is 403 UNBOUND_REQUEST, a wrong one is 403 BAD_STORE_TOKEN, and an expired one is 403 STORE_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”.

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.