POST /api/tally/envelopes/transfer

Reassign one ZEQ envelope coin to another machine's ZID. The whole coin moves — there is no partial-amount transfer and no fee.

Credits don't move. POST /api/tally/credits/transfer returns 410 by design — credits are non-transferable compute fuel (P19-A2). The only transferable asset is a minted ZEQ envelope coin, transferred here by its token_id.

Auth

Bearer. The caller must currently hold the coin (issued_to == your ZID, status = 'active', value > 0). Ownership is enforced inside the transaction — the WHERE clause is the lock.

Request

{
  "token_id": "ZT-9ad838d5e0f1…",
  "to":       "ZEQ07000000001"
}

Field	Type	Required	Notes
token_id	string	yes	The coin to move. Must start with ZT-.
to	string	yes	Recipient ZID (ZEQ…). Must exist; can't be your own ZID.

Response — 200

{
  "ok": true,
  "token_id":    "ZT-9ad838d5e0f1…",
  "to":          "ZEQ07000000001",
  "coin_value":  1.287,
  "transfer_id": "uuid"
}

coin_value is the coin's user_share (in ZEQ). The transfer is recorded with zero fee.

Errors

Status	error	Cause
400	token_id required (ZT-…)	Missing / malformed token_id.
400	recipient ZID required	Missing / malformed to.
400	cannot transfer to yourself	to == caller ZID.
403	You do not hold this envelope…	Caller isn't the active holder of the coin.
404	recipient not found	to ZID has no identity (no burning coins into the void by typo).
401	auth_required	No session / key.

Side effect: a tally_transitions row (type: transfer, memo: envelope_coin_transfer:<token_id>, fee: 0) is appended, hash-linked on the entangled state. The transfer id is deterministic (env:token:from:to), so a retried call is idempotent.

See also

• POST /api/tally/burn — burn-to-compute.
• GET /api/tally/credits/history/:zid — sent + received transfers and mints.