Skip to content
Space Invoices Documentation

Crypto and Web3 Businesses

Use this path when your business quotes, bills, or gets paid in cryptocurrency and needs standard invoices around that — not on-chain payment processing itself.

Common Underestimation

Teams assume “invoice in crypto” means one feature. It is really three separate, independently useful ones: showing a crypto amount next to a normal fiat invoice, pricing the document itself in a crypto asset, and recording that a payment came in as crypto. Most businesses only need one of the three. See the Crypto Guide for exactly how each works.

Who This Is For

  • crypto exchanges and brokerages invoicing fees, subscriptions, or B2B services
  • payment processors and payment facilitators that settle in crypto but still need standard business invoices
  • Web3/SaaS products billing in stablecoins (USDC, USDT)
  • OTC desks and market makers invoicing counterparties
  • mining pools and staking providers invoicing operators or node customers
  • agencies, contractors, and freelancers paid in crypto who need a normal-looking invoice for their own records or their client’s

Best Fit / Not A Fit

Best fit

  • you want a real invoice with tax handling, numbering, and a PDF, priced or settled in crypto
  • you need a documented, reportable EUR/fiat-equivalent value alongside a crypto amount
  • your entity is not in the UK and issues from a country where crypto invoicing is otherwise legally usable

Not a fit

  • you need Space Invoices to detect, verify, or process the on-chain payment itself — it only stores the wallet address you give it and lets you record that a payment happened; it does not watch the chain
  • you need cost-basis tracking, crypto accounting, or tax advice — Space Invoices converts amounts for document/reporting purposes only, it is not an accounting or tax engine for crypto holdings
  • your entity is UK-registered and you want a crypto-denominated invoice — HMRC treats cryptoassets as non-money, so this is blocked entirely
  • you must send e-invoices through Peppol/UBL, XRechnung, ZUGFeRD, NAV, KSeF, FatturaPA/SdI, or French e-reporting for a crypto-priced document — every one of these formats requires a fiat, ISO-currency-coded document and rejects a crypto-priced one with a 422; a plain fiat invoice with a crypto equivalent is fine for these paths, since the document itself is never in crypto
  • use an account key on your backend if you manage multiple business entities (for example a multi-brand desk or platform), or an entity key for a single business
  • use the JavaScript SDK to create documents from your own settlement or payment events
  • turn on crypto_equivalents only if you want a display-only crypto amount on fiat invoices; pricing a document itself in crypto (currency_code: "BTC", "USDC", …) needs no setting through the API (crypto_invoicing only controls the web app’s currency picker)

Entity Model

Typical model:

  • one entity per legal business unit that issues invoices
  • settings.crypto_wallets holds the wallet address(es) that entity accepts, one per asset code
  • your own systems remain the source of truth for on-chain settlement; Space Invoices only stores and prints what you tell it

First Sandbox Milestone

Validate this before go-live:

  1. configure crypto_wallets for the assets you accept
  2. depending on your use case: enable crypto_equivalents on a fiat invoice, or create one crypto-priced invoice with a crypto currency_code
  3. render the PDF and check the crypto amount, wallet address, and (for crypto-priced invoices) the fiat-converted totals
  4. record a type: "crypto" payment with a transaction hash as reference and confirm the document settles
  5. if you also export to accounting or file e-invoices, confirm which paths accept a crypto-priced document (see the Crypto Guide)

Bill a Customer in USDC

Invoice a customer in USDCtypescript
const _invoice = await sdk.invoices.create({
  currency_code: "USDC",
  customer: { name: "Acme Corp" },
  items: [{ name: "Monthly platform fee", quantity: 1, price: 500 }],
});
Checked with SDK v12.42.0
Create Invoice API →

Common Workflow and Gotchas

  • decide per use case whether you need crypto_equivalents (fiat invoice, informational crypto amount) or a crypto currency_code (the invoice itself is in crypto, no setting needed) — most businesses only need one
  • a document priced in crypto cannot be sent through any EN 16931-based e-invoicing format, NAV, KSeF, or FatturaPA/SdI — if you operate in a market with an e-invoicing mandate, keep the mandated document in fiat and use crypto_equivalents for the crypto amount instead
  • UK entities cannot issue crypto-priced documents at all — issue in GBP
  • crypto amounts round to the asset’s own decimals (8 for BTC/ETH, 6 for SOL, 2 for USDC/USDT), not the usual 2 decimal places
  • Space Invoices does not verify crypto payments on-chain; recording a type: "crypto" payment is a manual confirmation, the same as any other payment type
  • Crypto Guide — full reference for wallets, equivalents, crypto invoicing, and crypto payments
  • Invoices Guide — base invoice lifecycle
  • Entities API — settings.crypto_wallets, settings.crypto_equivalents, settings.crypto_invoicing (web-app picker preference)
  • Start free sandbox