Private Links API

Base URL and conventions

The hosted node answers at https://peal.network/links/v1, behind the same origin as this page. A node you run yourself serves the same paths on its own port. Bodies are JSON, responses are JSON, and errors are application/problem+json.

• Amounts are decimal strings of integer base units: "12500000" is 12.50 USDC. One exception is called out below.
• 32-byte values (namespace ids, account ids, keys, tags, roots) are 64 lowercase hex characters without 0x. Field elements are canonical little-endian encodings below the BLS12-381 scalar modulus; a value at or above it is rejected as malformed.
• Addresses are lowercase 0x strings. Timestamps are Unix seconds. Proofs are exactly 128 bytes, as hex.
• A namespace is one asset on one chain. Its id is SHA-256("peal-links/v1/namespace" || 0x00 || label), so sepolia/USDC always has the same id on every node that serves it.
• An account id is a field element derived from the namespace and the account's ed25519 public key. A position is the index of a receipt in the namespace's append-only log.

const res = await fetch('https://peal.network/links/v1/status');
const status = await res.json();
for (const ns of status.namespaces) {
  console.log(ns.label, ns.chain_name, ns.token_address, ns.decimals, 'decimals');
}
console.log('circuit', status.circuit_id);
console.log('signers', status.signers.length, 'threshold', status.signer_threshold);

What you can call today

The tables below document every route, writes included, so the wire format is on record. To make a payment today, use the hosted app.

Three ways a call is authenticated

A session authorizes product metadata only: requests, a profile, a backup. It confers no spending authority. Anything that moves value carries a proof and an account signature. The node cannot forge the signature, and cannot forge the proof under the proof system's soundness assumption; today's per-process key setup and unreviewed circuits mean that assumption is itself unaudited (see "What you are trusting" in Peal Private Links).

// 1. a nonce, good for ten minutes
const { nonce } = await (await fetch('https://peal.network/links/v1/auth/nonce')).json();

// 2. the wallet signs an EIP-4361 message naming the domain, the address and the nonce
const message = 'peal.network wants you to sign in with your Ethereum account:\n' + address + '\n\n'
  + 'URI: https://peal.network\nVersion: 1\nChain ID: ' + ns.chain_id   // the namespace's chain
  + '\nNonce: ' + nonce + '\nIssued At: ' + new Date().toISOString();
const signature = await wallet.signMessage(message);

// 3. a bearer token
const res = await fetch('https://peal.network/links/v1/auth/session', {
  method: 'POST', headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ message, signature }),
});
const { token, expires_at } = await res.json();
// then: headers: { authorization: 'Bearer ' + token }

Node

Ledger

The ledger is what the proofs are about. It is public: a record names the acting account, its old and new commitment, one receipt, the root the proof was made against, and the proof. It carries no amount and no counterparty. Which account acted, and when, is intentionally public, and the directory lets anyone who knows a wallet address link it to that account's activity.

const status = await (await fetch('https://peal.network/links/v1/status')).json();
const ns = status.namespaces[0].id;

const ledger = await (await fetch('https://peal.network/links/v1/ledger/' + ns)).json();
console.log('seq', ledger.seq, 'receipts', ledger.receipt_count, 'state root', ledger.state_root);

const books = await (await fetch('https://peal.network/links/v1/ledger/' + ns + '/accounting')).json();
console.log('minted', books.minted_total, 'withdrawn', books.withdrawn_total, 'outstanding', books.outstanding_liability);

const history = await (await fetch('https://peal.network/links/v1/ledger/' + ns + '/history?limit=3')).json();
for (const op of history.ops) {
  // a register names a pubkey, an op names an account, a mint names a deposit tag
  console.log(op.seq, op.kind, op.envelope.account ?? op.envelope.pubkey ?? op.envelope.intent.receipt);
}

Requests

A request is a manifest signed by the receiver's private account: the link id, the namespace, the receiving account and key, the amount, a title, a display name, the receiver's wallet address, an optional reference and expiry. The node stores it in clear, because the payer has to read it. The payer verifies the signature; the node also does, on creation.

The reservation is a courtesy between payers, not a rule the ledger enforces. Two clients that ignore it can both pay a request; the receiver gets both receipts.

Directory

The directory maps a wallet address to a private account, a receiving key and a display name, signed by the wallet as EIP-712 PealLinksAccount. Versions form a hash chain: each names the previous one's hash, and the node refuses a version that does not.

Inbox

A receipt is delivered as an envelope encrypted to the receiver's key: the node stores ciphertext, a recipient id and a time. Writing is open, so a payer needs no session; reading needs a fresh signature by the receiving account.

Deposits

A deposit is public on the chain and private on the ledger. The client proves a deposit relation over the amount and a random tag, registers the intent, then calls gateway.deposit(token, amount, tag). The node's watcher credits the tag after the namespace's confirmations. The tag hides the account; only the holder of the witness can claim the credit.

Withdrawals

A withdrawal is a send to a fixed burn account, proven like any payment, followed by a claim that reveals that one receipt's opening to the node. The settlement signers each check the opening against the ledger leaf and sign an EIP-712 Withdrawal for the gateway; two of three signatures make a certificate. Anyone can submit it to the chain; the recipient is inside the signed message.

Backups

Errors

Every error is application/problem+json with the same five fields. Match on code; the detail is for a human.

{
  "type": "https://peal.network/problems/stale_commitment",
  "title": "stale commitment",
  "status": 409,
  "code": "stale_commitment",
  "detail": "the account's commitment moved since this proof was made"
}

Limits

Cross-origin calls are allowed from any origin with GET, POST, PUT and OPTIONS, and the request headers content-type, accept, authorization, if-none-match and x-peal-inbox-auth; etag and x-peal-digest are exposed. There is no API key and no per-IP limit beyond the ones above.

Running your own node

Not public yet. The node is one Rust binary with a JSON profile: chains, tokens, gateways, confirmations, the accepted sign-in domains, and the settlement signer keys. With dev_mint on, it also mounts POST /dev/mint, which credits a pending deposit intent without a chain event, for local development only; the node refuses that flag with any mainnet namespace. Until the binary is published, the hosted node at https://peal.network/links/v1 is the only one you can call.

Where to go next

• Peal Private Links is the picture: the pieces and who sees what.
• API reference runs the public reads from the page.