WarpCoin WARP
← All documentation

WarpCoin Wallet Platform

WarpCoin is more than a coin and a node — it ships a full wallet platform that turns WARP into practical money for people and businesses. Every feature below is implemented in supported node code (Go) and exposed over the node's JSON-RPC API, and is also delivered as a polished web experience in WarpWallet (open source at kevinsegal/warpwallet).

The platform has five pillars:

  1. warp#tags — human-readable payment handles.
  2. Escrow — trust-minimized, signature-authorized fund holding.
  3. Merchant gateway — accept WARP on any site with invoices + webhooks.
  4. WarpScript contracts — a no-code smart-contract studio (see the WarpScript Contracts spec).
  5. Inter-planetary settlement — light-time-aware payments between worlds.

Security model

The platform never custodies your keys. Keys are generated and used on the client: ECDSA on NIST P-256, compressed public keys, Base58Check addresses (version 0x49, so addresses start with W), and double-SHA256 hashing — exactly the chain's scheme. In WarpWallet, private keys are sealed at rest with AES-256-GCM behind a PBKDF2 (SHA-256, 310k iterations) passphrase.

Privileged service actions (claiming a tag, releasing escrow) are authorized by a signature over a canonical action string, not a password or session:

digest    = sha256d( utf8(action) )           # e.g. action = "escrow:release:esc_…"
signature = ECDSA-P256(digest, privateKey)     # 64-byte r||s

The node re-derives the address from the supplied public key, verifies the signature, and checks the signer is permitted — the same trust model as on-chain transactions. A SignedAction is the JSON object { action, address, pubkey, signature }.

Multiple wallets & recovery phrases

A single node or desktop install can hold many wallets, each restorable from a seed phrase (a 12- or 24-word recovery phrase). When you create a wallet, WarpCoin generates the phrase from random entropy — BIP39-style: entropy plus a SHA-256 checksum encoded in 11-bit groups against a fixed 2048-word list — and derives the key from it (PBKDF2-HMAC-SHA512 → a deterministic P-256 key). Writing the phrase down is enough to restore the wallet on any device; an optional passphrase acts as a "25th word."

Because WarpCoin keys are NIST P-256 (not secp256k1), the scheme is self-contained and intentionally not interchangeable with secp256k1 BIP39/BIP32 wallets.

Wallets live as individual AES-256-GCM keystores in a store directory (~/.warpcoin/wallets) with a default pointer; the recovery phrase itself is never written to disk.

warpcoin wallet new --name primary            # 12-word phrase, shown once
warpcoin wallet new --name savings --words 24
warpcoin wallet import --name restored --mnemonic "word word … word"
warpcoin wallet import --name cold --key <hex-private-key>
warpcoin wallet list                           # * marks the default
warpcoin wallet use savings                     # switch the default
warpcoin send --wallet primary --to W… --amount 12.5

The desktop app exposes the same store: a wallet switcher, create-with-phrase (shown once in a confirmation dialog), and import by phrase or key.

warp#tags

A warp#tag is a short handle (warp#nova) that resolves to a WarpCoin address, so people can be paid without copying a long Base58 string. A tag is bound to an address by a signature from that address's key, proving ownership. Tags are 3–20 characters of a–z, 0–9, _.

Endpoint Method Purpose
GET /tag/resolve?tag=<tag> GET resolve a tag → { tag, address, createdAt }
GET /tag/reverse?address=<addr> GET reverse-lookup an address → tag
POST /tag/register POST claim a tag; body { tag, signed }

The register action string is warptag:register:<tag>:<address>.

Escrow

Escrow lets a buyer lock funds for a seller, with an optional arbiter for dispute resolution. Each state transition is authorized by a signature from a party permitted to make it:

created ──fund(buyer)──▶ funded ──release(buyer|arbiter)──▶ released
                           │  ╲
              dispute(buyer|seller)  refund(seller|arbiter)
                           ▼            ╲
                        disputed ────────▶ refunded
Endpoint Method Purpose
POST /escrow/create POST open an escrow { buyer, seller, arbiter?, amount, memo }
GET /escrow/list?address=<addr> GET escrows where the address is a party
GET /escrow/get?id=<id> GET fetch one escrow with its event log
POST /escrow/action POST { id, action, signed, note? } where action ∈ fund/release/refund/dispute

Action strings are escrow:<action>:<id>. This service is the coordination and authorization layer (state + signed approvals). For trustless on-chain custody, deploy the same agreement as a WarpVM contract: the chain holds the funds and releases them by consensus, with no contract private key — see WarpScript Contracts.

Merchant gateway

Businesses accept WARP without running custom infrastructure:

  1. Register a business with a payout address — receive a merchant id and an API key (wk_live_…).
  2. Create invoices from your backend with the API key.
  3. Hosted checkout — point the customer at /pay/<invoice> in WarpWallet; they pay in WARP from their wallet.
  4. Webhook — on payment, the gateway POSTs an invoice.paid event to your URL, optionally HMAC-SHA256 signed (X-Warp-Signature) when WARP_WEBHOOK_SECRET is configured.
Endpoint Method Purpose
POST /merchant/register POST { name, payoutAddress, webhookUrl? } → merchant + API key
GET /merchant/get?id=<id> GET public merchant info (never the API key)
POST /merchant/invoice/create POST Authorization: Bearer <apiKey>; { amount, memo?, orderRef?, redirectUrl? }
GET /merchant/invoice/get?id=<id> GET invoice for the checkout page
GET /merchant/invoices?merchantId=<id> GET list a merchant's invoices
POST /merchant/invoice/pay POST { invoiceId, tx } — broadcasts the signed transfer, confirms it pays the payout address ≥ the amount, marks paid, fires the webhook

Example — create an invoice (amounts in flux, 1 WARP = 100,000,000 flux):

curl -X POST https://your-node:8339/merchant/invoice/create \
  -H "Authorization: Bearer wk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"amount": 250000000, "memo": "Order #1234", "orderRef": "1234"}'

Inter-planetary settlement

WarpCoin targets cross-world payments. Across planets the binding constraint on settlement is not network latency but the speed of light. The node estimates one-way and round-trip light time between Solar System bodies so wallets can size realistic confirmation windows and contracts can settle on light-time-aware deadlines. On-chain, WarpVM consumes this as a deterministic trigger feed: the on_light_time trigger and light_time_elapsed condition fire once the round-trip delay to the destination world has elapsed since funding — alongside signed on_oracle feeds (see WarpScript Contracts).

Endpoint Method Purpose
GET /lighttime?from=<body>&to=<body>[&date=<RFC3339>] GET { lightTime, oneWayHuman, roundTripHuman, … }
GET /lighttime/bodies GET selectable bodies (Earth, Luna, Mercury, Venus, Mars, Jupiter, Saturn)

The model uses coplanar circular heliocentric orbits with J2000 mean longitudes and sidereal periods — accurate to a few percent for distance, which is more than enough to communicate scale (Mars is minutes away; Saturn is over an hour).

Try it: WarpWallet runs in self-contained demo mode out of the box (a built-in ledger grants new wallets a faucet), or set WARP_RPC_URL to point at a real WarpCoin node and use these endpoints directly.