TradeLock Getting Started

This guide is for managers and integration builders who want a first successful TradeLock submission without choosing between several overlapping docs.

TradeLock verification access is free. Submitted strategy signals are used solely to verify and preserve intent inside TradeLock and are not reused or shared outside TradeLock without the manager's explicit approval.

Doc version: 2.4

Updated: 2026-08-23

Use this order:

1. Create a sandbox API key.
2. Choose one submission path:

• Direct API with POST /api/set-target-portfolio (recommended)
• TradingView alerts through the Cloudflare relay

1. Confirm the first submission succeeds.
2. Use the full API reference for detailed endpoint behavior.

0) What you need first

1. A TradeLock manager account
2. A strategy in your workspace (examples below use Sandbox Strategy)
3. A sandbox API key from https://app.tradelock.net/app/api-keys (examples use <YOUR_SANDBOX_API_KEY>)
4. Valid symbols (SYMBOL or SYMBOL:EXCHANGE, for example AAPL:NASDAQ)

For equities and ETFs, a bare ticker uses the U.S. namespace. Qualify non-U.S. instruments with a supported exchange, such as VOD:LSE. Whitespace around the field and : separator is trimmed; whitespace inside a symbol or exchange token is rejected. If asset, symbol, and ticker are combined, they must resolve to the same instrument.

Base URL:

https://tradelock.net/api

1) Direct API path (recommended)

For most managers, the best first test is a full target portfolio submission.

1.1 Set portfolio targets

Endpoint: POST /api/set-target-portfolio

Headers:

• Content-Type: application/json
• X-Trader-Api-Key: <YOUR_SANDBOX_API_KEY>

Body:

{
  "strategy": "Sandbox Strategy",
  "targets": {
    "SPY": 33,
    "TLT": 33,
    "EEM": 10,
    "GSY": 15
  },
  "execution_anchor": "next_us_equity_open",
  "open_delay_minutes": 2,
  "idempotency_key": "signal-portfolio-20260406-001"
}

Notes:

1. This is the primary manager submission mode.
2. Symbols omitted from targets are treated as target 0%.
3. Targets do not need to sum to 100; unused weight stays in cash.
4. Existing cancellable pending trades for the same strategy are cancelled first by default.

cURL:

curl -X POST https://tradelock.net/api/set-target-portfolio \
  -H "Content-Type: application/json" \
  -H "X-Trader-Api-Key: <YOUR_SANDBOX_API_KEY>" \
  -d '{
    "strategy": "Sandbox Strategy",
    "targets": {"SPY": 33, "TLT": 33, "EEM": 10, "GSY": 15},
    "execution_anchor": "next_us_equity_open",
    "open_delay_minutes": 2,
    "idempotency_key": "signal-portfolio-20260406-001"
  }'

Successful acceptance returns 202 after TradeLock stores a durable job:

{
  "message": "Rebalance accepted for asynchronous processing.",
  "rebalance_id": "abc123",
  "strategy": "Sandbox Strategy",
  "status": "accepted",
  "status_url": "/api/rebalance-status?rebalance_id=abc123"
}

Save rebalance_id. Acceptance does not mean every leg has finished.

1.2 Explicit quantity mode

Use this when you need a direct buy or sell in shares or units.

Endpoint: POST /api/logTrade

{
  "user_strategy_name": "Sandbox Strategy",
  "asset": "AAPL:NASDAQ",
  "trade_type": "buy",
  "quantity": 10,
  "idempotency_key": "signal-qty-buy-20260406-001"
}

1.3 Single-symbol target allocation

Use this when you want to retarget one symbol without resetting the rest of the portfolio.

{
  "user_strategy_name": "Sandbox Strategy",
  "asset": "AAPL:NASDAQ",
  "allocation_percent": 30,
  "idempotency_key": "signal-single-target-20260406-001"
}

Rules:

1. Send allocation_percent
2. Omit side (trade_type / side)
3. Other symbols remain unchanged

2) TradingView via Cloudflare relay

Use this when TradingView is generating the signal and you want a relay between TradingView and TradeLock.

Flow:

1. TradingView sends JSON to the Cloudflare Worker relay.
2. The relay validates a shared relay gate key.
3. The relay forwards the payload to TradeLock.

Current example endpoint:

https://tradelock-tv-relay.tradelock.workers.dev/webhook/tradingview

2.1 What stays private

Never publish the real values for:

• the shared relay gate key
• the TradeLock API key

For the current Cloudflare relay example:

1. Open API Keys in the app and reveal the shared relay gate key only when you are configuring TradingView, Zapier, Make, n8n, or a similar webhook tool
2. Use that same shared value only inside your private alert or webhook message sent to the TradeLock relay endpoint
3. Do not put the real secret in public docs, screenshots, source control, or examples

Important:

• The shared relay gate key is only there to stop random public use of the relay. It is not used to identify users.
• The current relay example also expects api_key in the TradingView webhook body.
• That means the TradeLock API key must also stay private and is the value that identifies the manager.
• Use a dedicated TradeLock API key for this relay.

2.2 Quantity-mode TradingView payload

{
  "secret": "YOUR_WEBHOOK_SHARED_SECRET",
  "api_key": "YOUR_TRADELOCK_API_KEY",
  "strategy": "Momentum Core",
  "ticker": "{{ticker}}",
  "action": "{{strategy.order.action}}",
  "quantity": "{{strategy.order.contracts}}"
}

2.3 Allocation-mode TradingView payload

{
  "secret": "YOUR_WEBHOOK_SHARED_SECRET",
  "api_key": "YOUR_TRADELOCK_API_KEY",
  "strategy": "Momentum Core",
  "ticker": "{{ticker}}",
  "allocation_percent": 10
}

2.4 Duplicate protection

If TradingView can provide a stable order identifier, send it:

{
  "secret": "YOUR_WEBHOOK_SHARED_SECRET",
  "api_key": "YOUR_TRADELOCK_API_KEY",
  "strategy": "Momentum Core",
  "ticker": "{{ticker}}",
  "action": "{{strategy.order.action}}",
  "quantity": "{{strategy.order.contracts}}",
  "client_order_id": "{{strategy.order.id}}"
}

The relay also accepts idempotency_key directly.

3) Check execution status

Portfolio rebalance status

For set-target-portfolio, poll the returned ID:

GET /api/rebalance-status?rebalance_id=<REBALANCE_ID>

curl "https://tradelock.net/api/rebalance-status?rebalance_id=<REBALANCE_ID>" \
  -H "X-Trader-Api-Key: <YOUR_SANDBOX_API_KEY>"

States are accepted, planning, completed, partially_completed, and failed. Stop polling at one of the final three states. The terminal response contains result with the summary and leg results.

Individual trade status

Use status endpoint:

GET /api/trade-status?strategyName=<name>&tradeId=<id>

Example:

curl "https://tradelock.net/api/trade-status?strategyName=Sandbox%20Strategy&tradeId=<TRADE_OR_PENDING_ID>" \
  -H "X-Trader-Api-Key: <YOUR_SANDBOX_API_KEY>"

4) Unique Trade ID (idempotency_key)

Always send idempotency_key on write requests.

Rules:

1. New signal = new key
2. Retry same signal = reuse same key
3. Valid length: 8..200

For portfolio rebalances, the key is required. If submission times out or the connection drops, the outcome is unknown: retry the identical payload with the same key. Do not create a replacement key merely because the client did not receive 202.

For TradingView relay submissions, client_order_id is also accepted and mapped into the same duplicate-protection flow.

5) Live trade field policy

For live submissions, do not send:

• reported_date
• user_reported_price
• reference_price
• allocation_reference_price

These are only valid for CSV-import flows.

5a) Strategy settings that affect execution

Two optional strategy-level settings:

trade_hide_days — hides recent trades from public viewers for the specified number of days. Allowed values: 0 (show all, default), 30, 60, 90, 9999 (hides all trades from public). You as the manager always see the full history.

min_rebalance_move_pct — a drift filter for set-target-portfolio. Any leg whose notional move is smaller than this percentage of running capital is silently skipped. Default is 1 (1%). Set to 0 to disable filtering.

Set these on createStrategy or update-strategy:

{
  "strategy_name": "Sandbox Strategy",
  "trade_hide_days": 30,
  "min_rebalance_move_pct": 2
}

6) Next step: API reference

After the first successful signal, use:

• /docs/manager-api-reference/ for full endpoint behavior
• https://app.tradelock.net/app/integrations for in-app templates and copy-paste examples

7) Version notes

• 2.2 (2026-07-13)

1. Documented asynchronous portfolio acceptance and rebalance_id polling.
2. Added safe timeout and same-key retry guidance.

• 2.1 (2026-04-22)

1. Added section on trade_hide_days and min_rebalance_move_pct strategy settings.

• 2.0 (2026-04-06)

1. Reframed the quickstart as the single public getting-started guide.
2. Added TradingView submission guidance through the Cloudflare relay.
3. Added explicit public guidance on where the webhook secret should stay private.

• 1.3 (2026-03-17)

1. Documented that set-target-portfolio cancels existing pending trades for the strategy by default.
2. Added the cancel_pending_trades_first=false opt-out note.
3. Clarified that idempotent retries replay the original set-target-portfolio response.