Quickstart

Marketplace order with first-time TrustLayer users.

1. Health

GET /api/v1/health

2. Create deal

POST /api/v1/deals
Authorization: Bearer tl_test_…
Idempotency-Key: unique-per-attempt
Content-Type: application/json

{
  "external_id": "order_847291",
  "title": "Website development",
  "amount": "100",
  "rail": "crypto",
  "asset_code": "SOL",
  "buyer":  { "external_id": "mkt_buyer_99" },
  "seller": { "external_id": "mkt_seller_12" },
  "auto_finalize": true
}

The API key must include deals:create. Because this example sets auto_finalize: true, it must also include the separate deals:finalize scope. Response includes claim_url for unlinked parties. Send those to your users.

For crypto sessions, use funding:initiate for deposits, settlement:execute for release sessions, and transactions:cancel for cancellation sessions. These scopes do not grant on-chain signing authority.

3. Claim → accept → fund

User opens claim_url → signup → deal page → accept → Open Crypto Deposit.

4. Webhooks

Register an HTTPS endpoint and save the returned signing secret immediately. Verify HMAC-SHA256 over the exact raw body, deduplicate by event ID, and return a 2xx quickly.

5. Test safely

Use test credentials first. The integration sandbox demonstrates simulated failures; it does not move funds or call the API.