Zcash shielded & unified addresses

Integration requirements for Zcash unified/shielded addresses — accepted formats, memo rules, and MAYAChain-only routing.

SwapKit supports Zcash unified/shielded addresses (u1…) as a swap source and destination, in addition to transparent addresses. Shielded deposits hide the sender, so the flow differs from a normal swap in a few important ways covered here. Unified Zcash swaps are routed through MAYAChain only.

Supported address formats

Format	Prefix	Supported	Notes
Transparent	t1… / t3…	Yes	P2PKH / P2SH. Standard transparent flow.
Unified (Orchard)	u1…	Yes	ZIP-316 unified address. Treated as shielded.
Sapling	zs…	No	Not supported — reject client-side to avoid a 400.

Shielded deposit flow

When the source is a shielded Zcash address (u1…), SwapKit does not build the transaction, skips the balance check, and skips address screening. The /v3/swap response returns the memo, the deposit inboundAddress, and a shieldedMemo object — your wallet builds and broadcasts the deposit itself.

You must, in the same transaction:

1. Send the value output to inboundAddress.

2. Send a 0-value shielded note carrying the memo to shieldedMemo.unifiedAddress.

shieldedMemo.uivk (optional) is MAYAChain's unified incoming viewing key, used to decrypt the memo note.

For example, from a /swap response:

{
  "routeId": "4af9fa2e-6f1f-4475-b326-1f538adba657",
  "providers": ["MAYACHAIN"],
  "sellAsset": "ZEC.ZEC",
  "sellAmount": "0.02",                         // decimal ZEC — convert to zats for the tx
  "buyAsset": "BTC.BTC",
  "expectedBuyAmount": "0.00013088",
  "expectedBuyAmountMaxSlippage": "0.00012876",
  "sourceAddress": "u1j0dx09lc9007ntxcxc00mkm4xcrkn9hmadk6uwgky3e208maktgkgdq887hnshlhuy8ljvdunkzxayshd6t99y78ze8865h80uml20ur630y3w9mxa7e6tll2pprqhh2q2cvr9szre88",
  "destinationAddress": "bc1qdddfwkvqs0x74ues8pcrcp5sz03g8a2kqcx75t",

  // ── the three fields you need to build the deposit ──────────────────────────
  "inboundAddress": "t1H49fQdV8eAweCugmPoL28oppuLRcnv95C",
  "shieldedMemo": {
    "unifiedAddress": "u1m76w6hk7f3gqn3w2pgsvrn7ckedd3mtyxu6kugeyqeag6zqypjt8nvw7mnwzu80rrs2dahv8kz0py6y34zsecr8vhngzzjgq9djux8dkakcj33h4ta2g4lqg27470ppztalnajg08e3e",
    "uivk": "uivk1exampleviewingkeydonotusethisisadummyplaceholdervalueforillustrationonly000000000000000000000000000000000000000000000000000000000000000000000000"
  },
  "memo": "=:b:bc1qdddfwkvqs0x74ues8pcrcp5sz03g8a2kqcx75t/u1j0dx09lc9007ntxcxc00mkm4xcrkn9hmadk6uwgky3e208maktgkgdq887hnshlhuy8ljvdunkzxayshd6t99y78ze8865h80uml20ur630y3w9mxa7e6tll2pprqhh2q2cvr9szre88:12876:_/ts:5/0",
  // ────────────────────────────────────────────────────────────────────────────

  "fees": [ /* … */ ],
  "estimatedTime": { "inbound": 75, "swap": 6, "outbound": 600, "total": 681 },
  "meta": { /* … */ },
  "swapId": "5ef1d95f-1bf6-4e41-85fc-d51a890b2468"
  // note: NO "tx" field — the wallet builds the deposit
}

The deposit: ONE transaction, TWO recipients

[
  {
    // ← inboundAddress from /swap (transparent t1 vault). The VALUE goes here.
    "address": "t1H49fQdV8eAweCugmPoL28oppuLRcnv95C",
    "amount": 2000000,          // sellAmount "0.02" ZEC × 1e8 = 2,000,000 zatoshis
    "memo": null                // transparent output — no memo
  },
  {
    // ← shieldedMemo.unifiedAddress from /swap (Maya's u1 memo address).
    "address": "u1m76w6hk7f3gqn3w2pgsvrn7ckedd3mtyxu6kugeyqeag6zqypjt8nvw7mnwzu80rrs2dahv8kz0py6y34zsecr8vhngzzjgq9djux8dkakcj33h4ta2g4lqg27470ppztalnajg08e3e",
    "amount": 0,                // 0-value Orchard note — NEVER put value here
    "memo": "=:b:bc1qdddfwkvqs0x74ues8pcrcp5sz03g8a2kqcx75t/u1j0dx09lc9007ntxcxc00mkm4xcrkn9hmadk6uwgky3e208maktgkgdq887hnshlhuy8ljvdunkzxayshd6t99y78ze8865h80uml20ur630y3w9mxa7e6tll2pprqhh2q2cvr9szre88:12876:_/ts:5/0"
  }
]

Refund address & fund-loss guard

For a shielded source, a refund address is embedded in the Maya memo so funds can be returned if the swap fails. SwapKit defaults this to the swap's source address — there's no separate refundAddress to pass on /v3/swap. The embedded address is validated as a Zcash address; an invalid value returns invalidAddressForChain (400).

Fund-loss guard: a shielded-source Zcash swap whose memo does not contain a valid refund address is aborted with zcashShieldedRefundMissing (500) rather than returning a build-able deposit. Never broadcast a shielded deposit without the refund address in the memo.

Never send funds to shieldedMemo.unifiedAddress .

Memo size budgets

The Zcash memo is measured in UTF-8 bytes:

• Transparent source: 80 bytes (memo travels in an OP_RETURN).

• Shielded source: 512 bytes (memo rides the Orchard shielded note).

Errors

These Zcash-specific errors can surface during a shielded swap. See the full definitions in the /v3/swap error references.

• zcashShieldedRefundMissing (500) — fund-loss guard; refund address missing from the memo.

• zcashMemoTooLong (400) — memo exceeds the 80B (transparent) / 512B (shielded) budget.

• zcashShieldedMemoUnavailable (503) — MAYAChain shielded-memo support is off.

• memoTooLongForSourceChain (400) — generated memo too long for the source chain.

• zcashUnifiedAddressUnsupported (400, /v3/quote only) — non-Maya provider can't handle a unified address.

Provider limitations

Unified/shielded Zcash is MAYAChain-only. NEAR Intents and Flashnet cannot quote unified Zcash addresses yet, only MAYAChain routes are returned.