Contacts Documentation

My info

Display wallet information including locators (HTTP/HTTPS/Tor), public key, fee earnings, and total available credit.

Add detail for per-currency balance breakdowns
Add --show-auth to securely retrieve the auth code via a 5-minute tmpfs file
Auth code is never printed to logs — safe under docker logs

ExampleBare form — locators, public key, fee earnings, total available credit

eiou info

Same as above plus a per-currency balance breakdown

eiou info detail

Write the auth code to a 5-minute tmpfs file and print its path — never echoed to stdout or logs

eiou info --show-auth

Overview

Dashboard summary of total balances, active contacts, pending requests, and the most recent transactions. The default limit is 5; pass an integer to show more.

ExampleDefault view — 5 most recent transactions

eiou overview

Same view but with the last 10 transactions instead — pass any positive integer

eiou overview 10

Add contact

Send an outbound contact request. The receiver sees it as a pending incoming request until they accept it. Outbound-only — for an existing accepted contact use contact currency add to propose a new currency, or contact update to change settings.

Required (positional):

<address> — the contact's node URL (http://, https://, or .onion)
<name> — display name you'll use locally (quote multi-word names)

Optional flags (with defaults):

--fee — fee % you charge to relay this contact's transactions. Default 0 (free relay).
--credit — credit limit you extend, denominated in the chosen currency. Default 0, which means the relationship exists but no transactions can route through you yet (raise it later via contact update).
--currency — currency code (3–9 uppercase alphanumeric). Default VWL.
--requested-credit — credit limit you'd like the receiver to extend back to you. Sent as a suggestion only — they decide what to grant when they accept.
--message — short note attached to the request (≤ 255 chars).

ExampleBare form — just address and name; defaults to VWL, --fee 0, --credit 0

eiou contact add http://bob:8080 Bob

Set the fee, credit limit, and currency explicitly — the typical case

eiou contact add http://bob Bob --fee 0.1 --credit 1000 --currency VWL

Full form — also requests reciprocal credit and attaches a short note for the receiver

eiou contact add http://bob Bob --fee 1.0 --credit 100 --currency VWL --requested-credit 500 --message "Hey, it's Dave"

Mutual-add shortcut: if both sides run contact add against each other (without either side running accept), the cross-request is auto-finalized to accepted for the matching currency. Each side keeps the fee/credit it published in its own add — they don't have to match. Use add + accept when the receiving side wants to set its own fee/credit based on what the requester proposed.

View pending requests

List incoming and outgoing pending contact requests. Each incoming row prints a paste-ready eiou contact accept/decline hint with the requester's pubkey-hash, so you can copy the line directly.

Example

eiou contact pending

Accept contact

Accept a pending incoming contact request. Identify the request by the requester's pubkey-hash (printed by contact pending), or by their address or name. Repeat the --currency / --fee / --credit triplet to accept several currencies in one call.

Required:

positional <pubkey-hash | address | name> identifying the requester
at least one --currency CCY --fee F --credit C triplet (each --currency must be paired with a matching --fee and --credit)

ExampleSingle-currency accept — one --currency / --fee / --credit triplet

eiou contact accept <pubkey-hash> --currency VWL --fee 0.1 --credit 1000

Accept multiple currencies in one call by repeating the triplet — here VWL and EUR with different terms

eiou contact accept <pubkey-hash> --currency VWL --fee 0.1 --credit 1000 --currency EUR --fee 0.05 --credit 500

Apply (batched accept/decline/defer)

When an incoming request includes several currencies, contact apply lets you act on each one in a single call: accept some, decline some, defer the rest. Declines run before accepts so a decline EUR + accept VWL can't accidentally re-add the just-declined row. Deferred currencies stay pending and can be acted on later.

Decision flags (repeatable):

--accept CCY:fee:credit — accept this currency with the given fee and credit limit
--decline CCY — reject this currency (notifies the requester)
--defer CCY — leave this currency pending; no notification is sent

Example

eiou contact apply <hash> --accept VWL:0.01:1000 --decline EUR --defer XRP

Decline contact

Decline every pending currency on an incoming request in one shot. Each declined currency triggers a contact_currency_declined notification so the requester's outgoing-pending row is dropped on their side; a final contact_declined rejects the contact transaction itself.

Example

eiou contact decline <pubkey-hash>

View contact

Show full contact details: addresses, status, per-currency balances, fee/credit settings, and bidirectional available credit (refreshed via the ping/pong cycle, ~5 min). Resolves by name, address, or pubkey-hash.

ExampleResolve by display name — the easiest form once you've added the contact locally

eiou contact view Bob

Resolve by node URL — useful when you don't remember the local name

eiou contact view http://bob

Resolve by pubkey-hash — the most stable identifier; survives renames and address changes

eiou contact view <pubkey-hash>

List contacts

List all contacts grouped by status. Filter with --status accepted|pending|blocked to see only one bucket.

ExampleAll contacts grouped by status — no filter

eiou contact list

Filter to fully connected contacts only

eiou contact list --status accepted

Filter to outstanding requests (incoming and outgoing)

eiou contact list --status pending

Filter to contacts you've blocked

eiou contact list --status blocked

Search contacts

Substring-search your contact list by name. The query matches anywhere in the display name and is case-insensitive.

Example

eiou contact search Alice

Update contact

Update is flag-based — same shape as contact add, all fields optional. --currency is required only when --fee or --credit is set, since those are stored per-currency. Updates are local-only — the contact is not notified, and multi-field updates are not atomic across the name/per-currency boundary.

ExampleRename only — no --currency needed since the display name is shared across all currencies

eiou contact update Bob --name Robert

Change the fee for one currency — --currency is required because fees are stored per-currency

eiou contact update Bob --fee 1.5 --currency VWL

Change the credit limit on a different currency — same shape, different field

eiou contact update Bob --credit 500 --currency EUR

Combined update — rename the contact and overwrite both fee and credit on the same currency in one call

eiou contact update Bob --name Robert --fee 2.0 --credit 1500 --currency VWL

Ping contact

Check online status, response time, and per-currency chain heads. Ping verifies local chain integrity (gap detection, not just chain-head comparison); mismatches trigger an automatic sync, and unrecoverable gaps auto-propose a tx drop. Per-currency available credit values are written back to the local contact_credit table after a successful ping.

Example

eiou contact ping Bob

Block / unblock

Block a contact to reject incoming traffic from them — they cannot send transactions to you, and they cannot route P2P transactions through you. Existing balances are unchanged. unblock reverses the block.

ExampleBlock — rejects all incoming traffic from this contact and stops them routing through you

eiou contact block Bob

Reverse the block — restores both directions; balances were never touched

eiou contact unblock Bob

Delete contact

Removes a contact and the eIOUs associated with them from the local database. Settle outstanding balances before deleting — once the rows are gone, you can't read them back from disk.

Delete is not the same as cutting ties. If the other side still has you in their contacts, automatic background pings will resurface the contact (as a restored contact) and replay the transaction history back into your database. To actually stop interacting with someone, use block — that suspends the relationship without deleting state, and pings from the blocked side won't bring it back.

Example

eiou contact delete Bob

Per-currency operations

Once a contact is accepted on one currency, additional currencies are negotiated through the contact currency namespace — not by re-running contact add. The five subcommands below cover proposing, accepting, declining, inspecting, and locally cleaning up per-currency rows on an existing contact.

contact currency add

Propose a new currency on a contact you're already connected on. The remote receives a P2P request and can accept it (with their own fee/credit terms) or decline it. --fee and --credit are required.

eiou contact currency add Bob EUR --fee 0.05 --credit 500

contact currency accept

Accept a single per-currency request that's pending on an existing contact. You set your own --fee and --credit for this currency — they don't have to match the requester's.

eiou contact currency accept Alice EUR --fee 0.05 --credit 500

contact currency decline

Decline an incoming per-currency proposal. A notification is sent to the requester so their outgoing-pending row drops on their side immediately — this is the right command when you want the proposer to know the answer is no.

eiou contact currency decline Alice EUR

contact currency list

Show every currency configured for a single contact, with each row's status (pending / accepted / declined) and direction (incoming / outgoing). Useful when a contact spans several currencies and you want to see what's active.

eiou contact currency list Bob

contact currency remove

Remove a currency configuration from your local database. Local-only — the remote contact is not notified. Use this to clean up a stale outgoing-pending row on your side, not to reject an incoming proposal (use currency decline for that).

eiou contact currency remove Bob EUR