Download
Documentation

Transactions

Send eIOUs to contacts directly or through multi-hop P2P routing, inspect balances and history, return a received transaction to its sender, approve or reject pending P2P transactions when auto-accept is off, and manage payment requests. From the host, prepend docker exec <container> to every command shown below.

Send eIOU

Transfer value to a contact or to a node you can reach via P2P. The wallet checks for direct credit first; if there isn't enough, it broadcasts a P2P request and signs once a route returns. Currency must be 3–9 uppercase alphanumeric (e.g. VWL, EIOU).

  • Verify chain integrity locally (a gap auto-triggers sync, then a tx drop proposal if sync can't repair)
  • Compute available credit: contact's credit limit minus your outstanding eIOUs plus theirs to you
  • If amount fits within available credit, sign the transaction and send it
  • If not, broadcast a P2P request to find a route through other contacts
  • Once a route returns, sign and send to the first peer; final peer confirms back along the route
  • Otherwise, the transaction expires after p2pExpiration seconds (default 300)
ExampleSend to a contact by name — transport falls back to defaultTransportMode
eiou send Bob 50 VWL
Send to a full URI instead of a contact name — the scheme (http, https, .onion) is used directly
eiou send http://bob:8080 100 VWL
Same as the first form but with an optional description recorded on-chain
eiou send Bob 50 VWL "Payment for lunch"
Add --best to collect every RP2P route and pick the lowest-fee one — slower, ignored for .onion
eiou send Bob 50 VWL --best

Parameters: Name or Address/URI, Amount, Currency, optional description, optional --best flag.

--best (experimental): collects all RP2P route responses and selects the lowest-fee route. Adds latency. Ignored for .onion recipients (Tor uses fast mode internally).

Transport selection: when you pass a full address (http://Bob, https://Bob, Bob.onion) the scheme is used directly. When you pass a contact name with no scheme, the wallet falls back to defaultTransportMode (default: tor). Rate-limited to 30 sends per minute.

View balances

Show outstanding totals across all contacts, or with one specific contact. Each row reports sent, received, and net balance (negative net = you owe them).

ExampleShow outstanding totals across every contact
eiou viewbalances
Filter to a single contact — same row format, just one line
eiou viewbalances Bob

View transaction history

List transactions across all contacts or filter to a single contact. Output is capped by the maxOutput setting (default 5 lines) unless overridden with a limit argument; 0 means unlimited.

ExampleList recent transactions across every contact, capped by maxOutput
eiou history
Filter to a single contact — still capped by maxOutput
eiou history Bob
Same filter, but 0 as the limit means unlimited — print every transaction with this contact
eiou history Bob 0

Parameters (all optional): Name/Address/URI and a numeric limit (0 = unlimited).

Refund a received eIOU

Return a previously received transaction to whoever sent it, in full or in part. You name only the transaction; the wallet fixes the recipient (the original sender) and the currency from its own stored record, and caps the amount at what was actually received, so a refund can never be redirected, re-priced, or inflated. Only inbound, settled transactions are eligible. Rate-limited to 20 refund operations per minute.

  • The amount is optional: omit it to return the full remaining, or pass a smaller value for a partial refund.
  • The same transaction can be returned in several pieces over time, capped so the total returned never exceeds the amount received.
  • P2P return-routing fees are paid on top, from your balance; the original inbound fees the sender paid are sunk and cannot be recovered.
  • In the wallet web interface this is the Return to sender action on a received transaction's detail, where a Refunds table lists each refund alongside a running total of how much has been returned and how much remains.
ExampleReturn the full remaining amount to the original sender
eiou refund <txid>
Return part of it: a partial refund of 5
eiou refund <txid> 5

Parameters: the received transaction id (required), and an optional amount (omit to return the full remaining; a smaller value makes a partial refund).

P2P approvals

When autoAcceptTransaction is false, P2P transactions enter awaiting_approval status until you act on them. Without manual approval, awaiting transactions expire through normal cleanup and are never sent. Rate-limited to 30 P2P operations per minute.

  • Fast mode: a single route is shown; approve sends immediately.
  • Best-fee mode: multiple candidates returned; you pick one by index.
  • Tor destinations always force fast mode internally (Tor uses single-hop routing).

eiou p2p

List all P2P transactions awaiting approval, with their hash, amount, currency, route mode (fast or best-fee), and number of route candidates. Equivalent to eiou p2p list.

eiou p2p

eiou p2p candidates

Show the route candidates for a single P2P transaction (only meaningful in best-fee mode where multiple routes returned). Each candidate prints its index, total cost including relay fees, and the hop chain — pick an index for approve.

eiou p2p candidates <hash>

eiou p2p approve

Approve and send the awaiting transaction. In fast mode, no index is needed. In best-fee mode with multiple candidates, you must pass the candidate index from p2p candidates — the command errors out if you omit it.

eiou p2p approve <hash>
eiou p2p approve <hash> 2

eiou p2p reject

Cancel a pending P2P transaction. The route is released and the transaction will not be sent.

eiou p2p reject <hash>

Payment requests

Ask a contact to pay you a specific amount. If they approve, the eIOU is sent automatically through the full transaction pipeline (P2P routing, credit checks, DLQ retries). Rate-limited to 20 request operations per minute.

eiou request

List all incoming and outgoing payment requests. Equivalent to eiou request list.

eiou request

eiou request create

Create and send a payment request to a contact. Optional description is shown to the recipient and recorded on-chain when they approve. If multiple contacts share the same name, create errors out with a list of matching addresses — pass the address instead.

eiou request create Alice 25.00 VWL "Dinner last week"

eiou request approve

Approve an incoming request, which immediately calls send internally. The optional note is appended to the on-chain description with | and capped against the 255-char description ceiling — the command rejects with a clear error if it doesn't fit.

eiou request approve req_abc123def456
eiou request approve req_abc123def456 "paid via coinbase txid abc"

eiou request decline

Decline an incoming payment request. The requester is notified so their outgoing request drops on their side.

eiou request decline req_abc123def456

eiou request cancel

Cancel an outgoing request you created, while it's still pending. A cancellation message is sent; if the recipient already approved before the cancel arrives, the payment takes priority and the cancellation is ignored.

eiou request cancel req_abc123def456