API Specification

The SDK is built on top of HTTP/JSON APIs. You can also call these directly from backends, bots, or services.

4.1 Authentication

Most project-level endpoints require a Project API Key or a signed message using the project admin key.

Headers example:

X-Project-Id: my-project-001
X-Api-Key: <redacted>
Content-Type: application/json

---

4.2 Key Endpoints

4.2.1 Create Private Deposit

POST /api/v1/pools/:poolId/deposit

Request:

{
  "asset": "USDC",
  "amount": "1000",
  "originChainId": 8453,
  "userPublicAddress": "0xUser",
  "txHash": "0xBridgeTxHash"
}

Response:

{
  "status": "pending",
  "noteId": "note-123",
  "commitment": "0x...",
  "expectedConfirmationBlocks": 12
}

---

4.2.2 Execute Private Action

POST /api/v1/pools/:poolId/actions

Request:

{
  "action": "swap",
  "payload": {
    "fromAsset": "USDC",
    "toAsset": "ZK",
    "amountIn": "500",
    "minAmountOut": "490"
  },
  "proof": "0xZkProofData",
  "publicInputs": ["0x...", "0x..."]
}

Response:

{
  "status": "accepted",
  "actionId": "act-789",
  "batchHint": "batch-xyz"
}

---

4.2.3 Withdraw from Pool

POST /api/v1/pools/:poolId/withdraw

Request:

{
  "asset": "USDC",
  "amount": "300",
  "destinationAddress": "0xUser",
  "destinationChainId": 8453,
  "proof": "0xWithdrawProof",
  "publicInputs": ["0x...", "0x..."]
}

Response:

{
  "status": "queued",
  "withdrawId": "wd-456",
  "bridgeExpected": true
}

---

4.2.4 Get Pool State Snapshot (Public Metadata)

GET /api/v1/pools/:poolId/state

Response:

{
  "poolId": "pool-DEX-001",
  "assets": [
    { "symbol": "USDC", "totalDeposits": "1000000" },
    { "symbol": "ZK", "totalDeposits": "500000" }
  ],
  "totalVolume24h": "250000",
  "batchHeight": 1024
}

Note: No per-user balances are ever exposed. This is aggregated metadata.