API reference - Numpay Docs

Specification, not yet live. These endpoints are planned and don’t resolve yet.

Environment	Base URL
Production	`https://api.numpay.io/zk`
Testnet	`https://testnet-api.numpay.io/zk`

POST /verify

Verify a ZK payment proof and get a payment token.

object

required

Groth16 proof.

array

required

Public signals of the proof.

object

required

ElGamal ciphertext.

object

required

Range proof for the amount.

array

required

Public signals of the range proof.

string

required

Commitment to the sender.

string

required

Recipient’s encryption key.

string

required

The x402 resource being paid for.

number

required

Proof creation time.

Response

{
  "valid": true,
  "paymentToken": "eyJhbGciOi…",
  "expiresIn": 300,
  "privacy": { "amountEncrypted": true, "senderHidden": true, "proofSystem": "groth16" }
}

POST /settle

Settle the payment on-chain. Gas is paid by the Numpay relayer.

object

required

array

required

object

required

string

required

From /verify.

string

required

string

required

Response

{
  "status": "success",
  "txSignature": "…",
  "blockNumber": 123456,
  "gasFeePaidBy": "numpay-relayer",
  "privacy": {
    "amountVisibleOnChain": false,
    "senderAddressHidden": true,
    "observerCannotLinkTransactions": true
  }
}

GET /phone/resolve/

Resolve a phone number to a wallet through the encrypted mapping.

Response

{ "wallet": "…", "phoneHash": "…", "encryptedMapping": true, "verified": true }

POST /phone/link

Link a phone number to a wallet.

string

required

string

required

string

required

Wallet signature over the link.

string

required

​POST /verify

​POST /settle

​GET /phone/resolve/

​POST /phone/link

POST /verify

POST /settle

GET /phone/resolve/

POST /phone/link