Proxy API

Server-side Canton ledger access using scoped API keys.

---

Overview

The Proxy API allows backend services, bots, and automation workflows to interact with the Canton ledger as a specific party. This is the only external API available to third-party applications — all admin and Canton APIs are internal to the portal and not accessible externally.

To use the Proxy API, request a scoped API key from your instance operator. Keys are created in the admin panel and bound to a specific Canton party with optional restrictions.

All requests are:

• Bound to a single party configured on the API key
• Restricted by package/template/choice whitelists (if configured)
• Rate-limited per endpoint
• Audit-logged with operation, status, duration, and IP

---

Authentication

Include the API key in the X-API-Key header:

X-API-Key: cwp_a1b2c3d4e5f6...

Obtain a key from your instance operator — keys are created in the admin panel under Scoped API Endpoints and shown only once at creation.

---

Endpoints

Query Contracts

POST /api/proxy/query

Query active contracts visible to the bound party.

curl -X POST https://your-vault/api/proxy/query \
  -H "X-API-Key: cwp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "abc123...#DeFi:Position", "filter": {}}'

// Request
{
  "templateId": "abc123...#DeFi:Position",
  "filter": { "owner": "party::..." }
}

// Response
{
  "success": true,
  "data": [
    {
      "contractId": "00abc...",
      "templateId": "abc123...#DeFi:Position",
      "payload": { "owner": "party::...", "shares": "100.0" }
    }
  ]
}

Field	Type	Required	Description
templateId	string	Yes	Fully qualified template ID (packageId#Module:Template)
filter	object	No	Payload field filters

---

Create Contract

POST /api/proxy/create

Create a new contract instance.

curl -X POST https://your-vault/api/proxy/create \
  -H "X-API-Key: cwp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "abc123...#Orders:LimitOrder",
    "payload": {
      "trader": "party::...",
      "inputToken": "ETH",
      "outputToken": "USDC",
      "inputAmount": "1.0"
    }
  }'

// Response
{
  "success": true,
  "data": { "contractId": "00def..." }
}

Field	Type	Required	Description
templateId	string	Yes	Fully qualified template ID
payload	object	Yes	Contract create arguments

---

Exercise Choice

POST /api/proxy/exercise

Execute a choice on an existing contract.

curl -X POST https://your-vault/api/proxy/exercise \
  -H "X-API-Key: cwp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "00abc...",
    "templateId": "abc123...#Orders:LimitOrder",
    "choice": "Fill",
    "argument": { "filler": "party::...", "fillAmount": "1.0" }
  }'

// Response
{
  "success": true,
  "data": { "exerciseResult": { "outputAmount": "3000.0" } }
}

Field	Type	Required	Description
contractId	string	Yes	Target contract ID
templateId	string	Yes	Fully qualified template ID
choice	string	Yes	Choice name to exercise
argument	object	No	Choice arguments (default {})

---

Access Control

Proxy requests are validated against the endpoint's configuration:

1. API key lookup — key is SHA-256 hashed and matched against stored endpoints
2. Enabled check — endpoint must be enabled
3. Rate limit — requests in the last minute are counted against the configured limit
4. Package/template whitelist — if allowed_packages or allowed_templates is set, the template's package prefix must match
5. Choice whitelist — for exercise requests, if allowed_choices is set, the choice must be listed

If no restrictions are configured, all templates and choices are allowed.

---

Error Responses

Status	Meaning
400	Missing required fields
401	Missing or invalid API key
403	Template or choice not allowed for this endpoint
429	Rate limit exceeded
500	Canton ledger error

---

Template ID Format

Template IDs follow the format {packageId}#{moduleName}:{templateName}:

abc123def456...#DeFi:Position
abc123def456...#Finance.Orders:LimitOrder

The package ID is the hex hash returned when uploading a DAR file.

---

Example: Trading Bot

import requests

API_KEY = "cwp_a1b2c3d4..."
BASE_URL = "https://your-vault.example.com"
TEMPLATE = "abc123...#Trading:Order"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Query open orders
orders = requests.post(f"{BASE_URL}/api/proxy/query", headers=headers, json={
    "templateId": TEMPLATE
}).json()["data"]

# Cancel an order
for order in orders:
    requests.post(f"{BASE_URL}/api/proxy/exercise", headers=headers, json={
        "contractId": order["contractId"],
        "templateId": TEMPLATE,
        "choice": "Cancel",
        "argument": {}
    })

---

Next Steps

• Canton Contracts — Template ID format, type mapping
• App Development — Build dock apps with the browser SDK