Relay API

​

SDK-facing route map

• POST /transact UTXO submit
• POST /transact_swap UTXO swap submit
• GET /status/:id async job status
• POST /viewing-key/register viewing-key registration
• GET /commitments commitment list for Merkle rebuild
• GET /merkle-root latest on-chain root

​

POST /transact (UTXO)

{
  "proof_bytes": "<base64 256-byte proof>",
  "public_inputs": "<base64 264-byte blob>",
  "recipient": "<base58 optional, required for withdrawals>",
  "encrypted_notes": ["<base64 compact chain note>"]
}

• root[32]
• publicAmount[8] (i64, LE)
• extDataHash[32]
• mintAddress[32]
• nullifiers[64]
• commitments[64]
• chainNoteHash[32]

• proof_bytes must decode to exactly 256 bytes.
• public_inputs must decode to exactly 264 bytes.
• recipient is required when publicAmount < 0.
• encrypted_notes supports max 2 entries and bounded total bytes.

​

POST /transact_swap (UTXO swap)

{
  "proof_bytes": "<base64 256-byte proof>",
  "public_inputs": "<base64 264-byte blob>",
  "output_mint": "<base58>",
  "recipient_ata": "<base58>",
  "recipient": "<base58 optional wallet>",
  "min_output_amount": 1000000,
  "encrypted_notes": ["<optional base64 notes>"]
}

• Requires withdrawal semantics (publicAmount < 0).
• Submits TransactSwap, then queues swap execution job.
• Response includes swap_state_pda and nullifier when available.

​

POST /viewing-key/register

{
  "user_pubkey": "<wallet base58>",
  "viewing_key": "<32-byte hex>",
  "identifier": "<optional 64-hex>",
  "signature": "<base64 64-byte ed25519 signature>"
}

• Signature must be over the fixed Cloak sign-in message.
• If identifier is omitted, relay computes sha256(user_pubkey || viewing_key_hex).
• Relay stores identifier + viewing key; no raw wallet column is required.

​

GET /commitments

{
  "commitments": [
    { "index": 0, "commitment": "<hex32>" }
  ],
  "count": 1
}

• Use this endpoint when rebuilding Merkle state for proof generation.

​

GET /merkle-root

{
  "root": "<hex32>",
  "merkle_tree": "<base58>"
}

​

GET /status/:id

{
  "success": true,
  "data": {
    "request_id": "<uuid>",
    "status": "pending|processing|completed|failed",
    "tx_id": "<optional>",
    "solana_signature": "<optional>",
    "error": "<optional>",
    "created_at": "<timestamp>",
    "completed_at": "<timestamp|null>"
  }
}