← Developer portal

Reference · v1

Partner API reference

Search endpoints, inspect example payloads and copy cURL, JavaScript or Python requests. The authoritative machine-readable contract is available from /api/v1/openapi.

11 endpoints · Base URL: https://YOUR_TRUSTLAYER_HOST/api/v1

GET/health

Health check

Check whether the Partner API route is reachable. Does not prove database or settlement health.

Scope: Public
curl request
curl -X GET 'https://YOUR_TRUSTLAYER_HOST/api/v1/health' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json'
Example response
{"ok":true}
GET/openapi

OpenAPI document

Fetch the OpenAPI 3.0 schema for the current API version.

Scope: Public
curl request
curl -X GET 'https://YOUR_TRUSTLAYER_HOST/api/v1/openapi' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json'
Example response
{"openapi":"3.0.3"}
GET/deals

List deals

Search and filter partner deals with cursor pagination.

Scope: deals:read
curl request
curl -X GET 'https://YOUR_TRUSTLAYER_HOST/api/v1/deals' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-123-attempt-1'
Example response
{"data":[],"next_cursor":null,"has_more":false,"environment":"test"}
POST/deals

Create deal

Create a crypto escrow agreement. Use an Idempotency-Key for safe retries.

Scope: deals:create
curl request
curl -X POST 'https://YOUR_TRUSTLAYER_HOST/api/v1/deals' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-123-attempt-1' \
  --data '{"external_id":"order_123","title":"Design project","amount":"25.00","rail":"crypto","asset_code":"USDC","buyer":{"external_id":"buyer_1"},"seller":{"external_id":"seller_1"}}'
Example response
{"data":{"id":"<deal-uuid>","status":"draft"},"request_id":"<request-id>"}
GET/deals/{id}

Retrieve deal

Retrieve a deal by TrustLayer UUID or partner external ID within the API key environment.

Scope: deals:read
curl request
curl -X GET 'https://YOUR_TRUSTLAYER_HOST/api/v1/deals/<deal-id>' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json'
Example response
{"data":{"id":"<deal-uuid>","status":"draft"},"request_id":"<request-id>"}
POST/deals/{id}/finalize

Finalize agreement

Finalize a draft agreement and record its lifecycle event. Requires the separate deals:finalize scope.

Scope: deals:finalize
curl request
curl -X POST 'https://YOUR_TRUSTLAYER_HOST/api/v1/deals/<deal-id>/finalize' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-123-attempt-1'
Example response
{"data":{"id":"<deal-uuid>","status":"awaiting_payment"}}
POST/crypto/sessions

Create crypto session

Create a time-limited session URL. Deposit requires funding:initiate, release requires settlement:execute, and cancellation requires transactions:cancel. API permission does not grant signing authority.

Scope: action-specific scope
curl request
curl -X POST 'https://YOUR_TRUSTLAYER_HOST/api/v1/crypto/sessions' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-123-attempt-1' \
  --data '{"deal_id":"<deal-uuid>","action":"deposit","milestone_index":0}'
Example response
{"data":{"url":"https://<trustlayer-host>/...","expires_at":"<iso-time>"}}
POST/users/link

Link external user

Link a partner-owned external user ID to a TrustLayer user ID.

Scope: users:link
curl request
curl -X POST 'https://YOUR_TRUSTLAYER_HOST/api/v1/users/link' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"external_user_id":"buyer_1","trustlayer_user_id":"<user-uuid>"}'
Example response
{"data":{"linked":true},"request_id":"<request-id>"}
GET/events

Poll events

Poll partner events using a cursor. Events are scoped to the key environment.

Scope: events:read
curl request
curl -X GET 'https://YOUR_TRUSTLAYER_HOST/api/v1/events' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json'
Example response
{"data":[],"next_cursor":null,"environment":"test"}
GET/webhooks

List webhook endpoints

List endpoints for the API key environment. Signing secrets are never returned.

Scope: webhooks:manage
curl request
curl -X GET 'https://YOUR_TRUSTLAYER_HOST/api/v1/webhooks' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json'
Example response
{"data":[],"request_id":"<request-id>"}
POST/webhooks

Register webhook endpoint

Register an HTTPS endpoint. Save the returned signing_secret immediately; it is shown only once.

Scope: webhooks:manage
curl request
curl -X POST 'https://YOUR_TRUSTLAYER_HOST/api/v1/webhooks' \
  -H 'Authorization: Bearer $TRUSTLAYER_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://your-service.example/webhooks/trustlayer","description":"Order updates"}'
Example response
{"data":{"id":"<endpoint-id>","signing_secret":"<shown-once>"}}

Examples use placeholders and illustrative responses. Keep API keys server-side. Use an Idempotency-Key for write requests, verify webhook signatures against the raw body, and treat settlement as confirmed only by the underlying settlement record/transaction.