Available

TradeEngine

post/v1/trade-engine/settlement

Compute a trade's settlement — each side's value and who owes whom (TradeValue = OriginalPrice + RequestedAmount - WillingToPay per listing). All listings in a trade must share one currency; a trade mixing currencies is rejected.

curl -X POST https://api.tbbnetwork.com/v1/trade-engine/settlement \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "listingIdsA": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "listingIdsB": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "extraAmountA": 1,
  "extraAmountB": 1
}'

Request body

Field	Type	Required
listingIdsA	string[]	yes
listingIdsB	string[]	yes
extraAmountA	number	—
extraAmountB	number	—

Response (201)

Field	Type	Required
currency	string	—
sideAValue	number	—
sideBValue	number	—
difference	number	—
owingSide	A \| B \|	—

Example 201 response

{
  "currency": "USD",
  "sideAValue": 1,
  "sideBValue": 1,
  "difference": 1,
  "owingSide": "A"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}