Protocol v1

The VelarumPay protocol

Two small, validated formats carry everything: velarum.payment_request.v1 (the exact on-chain facts) and velarum.transaction_context.v1 (the human-readable explanation the user reviews).

Download the canonical Payment Request JSON Schema and Transaction Context JSON Schema.

Golden rule: payment facts come from the payment object only — never from display or metadata. What the user signs is exactly what is in payment.

Payment Request v1

The payment object describes the money movement. Fields:

Field	Meaning
`rail`	Payment rail: `base_usdc` or `stellar_xlm`.
`network`	`base_mainnet` for Base USDC; `stellar_public` / `stellar_testnet` for XLM.
`asset`	Asset symbol, e.g. `USDC` or `XLM`.
`amount`	Exact decimal string, e.g. `"42.00"`. Never a float.
`to`	Recipient address (EVM `0x...` or Stellar `G...`).
`token_contract`	Token contract (Base USDC: the canonical USDC contract).
`chain_id`	EVM chain id (Base mainnet = `8453`).
`decimals`	Token decimals (USDC = `6`).

Plus payee (name, verified flag) and policy (e.g. requires_user_approval: true).

Validated v0.1 example rails

Rail	Network	Address	Notes
`base_usdc`	`base_mainnet`	`0x...`	chain id 8453, canonical USDC contract, decimals 6.
`stellar_xlm`	`stellar_public` / `stellar_testnet`	`G...`	Stellar public key.

evm_erc20 is accepted only as a migration alias and normalizes to base_usdc. Validation support is not a cross-platform release-support claim: your Android/iOS build must explicitly advertise and test the corresponding signer and broadcaster.

Transaction Context v1

This is what the user actually reads before signing. It explains why this payment, in plain language.

{
  "protocol": "velarum.transaction_context.v1",
  "transaction_id": "txn_demo_1",
  "connection_id": "conn_demo_1",
  "type": "developer_test",
  "title": "Developer test checkout",
  "summary": "A local developer test context for wallet review.",
  "costs": { "total": "42.00", "currency": "USDC" },
  "truth_fields": [],
  "evidence": []
}

Field	Meaning
`title` / `summary`	Short, human-readable description shown in the wallet.
`costs`	Total and currency, as decimal strings.
`truth_fields`	Verifiable facts (e.g. an order id) the user can trust.
`evidence`	Optional supporting references.

Validation

The @velarumpay/protocol package exports validators you can run before sending:

import { normalizePaymentRequestV1, normalizeTransactionContextV1 } from "@velarumpay/protocol";

const result = normalizePaymentRequestV1(payload);
if (!result.ok) console.error(result.errors);

The validators never sign, never store keys, and never create an automatic payment path. They only check and normalize.

For the HTTP surface and structured error envelopes, download the Platform API OpenAPI document.