# Eigenbeleg API

> Eigenbelege (self-issued proofs of payment for German bookkeeping; never invoices) for the payments of a person's own blockchain addresses: network fees, storage deposits, transfers. PDF/A-2b and CSV, with the EUR rate of each payment's day and its source. Paid per request with x402.

People use the web UI at https://eigenbeleg.le-space.de/ui/ instead: it does everything in their browser, for free, and sends nothing here. This API is for agents acting for someone.

**Businesses only.** The paid API sells to businesses (§ 14 BGB, German Civil Code) under its terms of business: https://eigenbeleg.le-space.de/ui/#agb (German binding, English for reading). By paying, the customer confirms they act for their business; buy only for someone who does. Private persons use the web UI, free. Prices include 19% German VAT; an invoice comes on request (e-mail to contact@le-space.de with the payment's transaction hash and the billing address).

## Buy

- POST https://eigenbeleg.le-space.de/eigenbeleg/preview: free, the same body without `payer`; counts and totals, no files. Check here first.
- POST https://eigenbeleg.le-space.de/eigenbeleg: USDC on NEAR (near:mainnet): $0.10 to le-space.near. The payer picks one of the 402's accepts; this API's relayer pays the gas on each.
- POST https://eigenbeleg.le-space.de/eigenbeleg/subscribe: a subscription, 12 monthly Kontoauszüge by mail, paid once: $1.20 (12 × the price, unless set apart); POST https://eigenbeleg.le-space.de/eigenbeleg/subscribe/<months> buys 1 to 12 months in advance at months × the price of one request. The same body as POST /eigenbeleg with `email` and without `period`; `document` is kontoauszug by default. From the 2nd of each month the statement for the month before goes to that address; the answer and every mail carry the cancel link, which deletes everything (no refund of the remaining months). Chain, addresses, payer, e-mail address and options are kept encrypted until the last statement or the cancellation; everything else this API does stays unstored.
  1. Send the body; the answer is 402 with a `PAYMENT-REQUIRED` header (base64 JSON, x402 v2, scheme `exact`).
  2. Sign what it asks for and send the same request again with `PAYMENT-SIGNATURE`. On NEAR: one NEP-366 delegate action with one `ft_transfer` of USDC (the payer needs USDC and a USDC storage registration, no NEAR). On Base or Ethereum: one EIP-3009 `transferWithAuthorization` of USDC (the payer needs USDC, no ETH).
  3. The answer carries the files and `PAYMENT-RESPONSE` (the transaction). If reading the chain fails, nothing is charged.
  Clients: @x402/fetch with @x402/near or @x402/evm (JavaScript), or this repository's agent: npm run agent -- --help.

## Body

{
  "chain": "near" | "akash" | "filecoin" | "aleph"   (GET https://eigenbeleg.le-space.de/blocks lists them and their networks),
  "network": "mainnet" | "testnet",           where the payments were made,
  "addresses": ["own-account.near"],          one to ten own addresses,
  "period": { "month": "YYYY-MM" } or { "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }   finished days, at most 92,
  "format": "pdf" | "csv" | "json",          json: every file, PDFs base64,
  "document": "eigenbelege" | "kontoauszug" | "beide",
  "payer": { "name": "…", "address": "street, postcode town" }   printed on the documents; used for this response only, never stored or logged,
  "number": "EB-2026-001",                    optional, first number of the payer's own range,
  "includeKinds": ["fee", "storage"],         optional: of the chain's kinds in GET /blocks (fee, storage, transfer, call; storage is NEAR's)
  "logo": false,                              optional: the chain's mark, small, beside the title
  "email": "belege@example.org",              optional: the files also by mail, once the payment is settled
  "language": "en" | "de"                     optional, default en: the language of the mail (the documents are German either way)
}

## Notes

- aleph (Aleph Cloud credits, by the Ethereum address): one finished month (`period.month`). `document` kontoauszug (the default) is a Verbrauchsauszug (VA-…), usage per day and resource, valued at the USD price per credit and the ECB rate of the day; eigenbelege gives one Eigenbeleg per purchase of credits (kind swap: a token for credits, in USD at the ECB rate, with the paying transaction's hash on Ethereum or Base). Usage itself gets no Eigenbeleg: it is no single payment.
- The documents are in German. An Eigenbeleg counts only once the payer signs it; whether a tax adviser accepts it is theirs to decide.
- email: the files go as attachments (stable names: EB-….pdf, KA-….pdf, EB-….csv; subject "Eigenbeleg EB-… · chain network · period"), so a document management system's inbox can sort them. The answer says `mail: queued` (format json) or carries X-Eigenbeleg-Mail: queued. The address is used for that one mail only.
- As a skill (Agent Skills format, agentskills.io): https://github.com/Le-Space/eigenbeleg-agent/tree/main/plugin/skills/eigenbeleg-api – these steps for Claude Code and other agents that read SKILL.md. Without paying, on the user's own machine (nothing sent here): https://github.com/Le-Space/eigenbeleg-agent/tree/main/plugin/skills/eigenbeleg-local, i.e. `npm run local` in a checkout.
- Nothing is stored beyond the request. Source (AGPL-3.0-or-later): https://github.com/Le-Space/eigenbeleg-agent