Create Settlement

post/api/trade/v1/enterprise/{enterpriseId}/account/{accountId}/settlements

The Create Settlement API initiates a settlement between the requester and a designated counterparty. It will create a Settlement object and an Affirmation object for every trading account involved. Requester must also include a signed payload as part of their request. Locks will be placed on every trading account and stored in the Affirmation object.

Path Parameters

  • enterpriseIdstringRequired
    Enterprise ID
  • accountIdstringRequired
    Trading Account ID

Request Body

payload string
This payload must be cryptographically signed with a trading account's private key to authorize the movement of funds
Example: {"version":"1.2.0","accountId":"59cd72485007a239fb00282ed480da1f","amounts":[{"accountId":"5e20faa843795147000da79b8a01f757","sendSubtotal":"1000000","sendAmount":"1000000","sendCurrency":"ofctusd","receiveAmount":"1000000","receiveCurrency":"ofctbtc"},{"accountId":"59cd72485007a239fb00282ed480da1f","sendSubtotal":"1000000","sendAmount":"1000000","sendCurrency":"ofctbtc","receiveAmount":"1000000","receiveCurrency":"ofctusd"}],"nonceHold":"zq/aCtZC4XOlDyRGFdlsww==","nonceSettle":"FnG6xbzehNn0o/0Qt3UeUg=="}
signature string
The "payload" cryptographically signed by trading account
Example: 1f0f5b4b45106f98bb9c67ba525ead5bd919f14ab1258e25ab16f9d530856f307228431104f39eb0a249f88cd66a79abfe7aee1de96a288af237b4202c82dd8919
trades array[Trade]
id string <uuid>
Trade ID
baseAccountId string required
Trading account ID that is sending base currency
quoteAccountId string required
Trading account ID that is sending quote currency
status string required
The status of the trade
Allowed values: pending overdue rejected affirmed settled failed
Example: pending
timestamp string <date-time>required
ISO date string
baseAmount string required
Amount of base currency in fractional units
quoteAmount string required
Amount of quote currency in fractional units
baseCurrency string required
Base offchain currency of currency pair. (eg. for trading pair BTC/USD, ofcbtc would be "baseCurrency")
quoteCurrency string required
Quote offchain currency of currency pair. (eg. for trading pair BTC/USD, ofcusd would be "quoteCurrency")
baseReceiveAmount string
Amount of base receive currency that the baseAccount expects to receive (in fractional units)
quoteReceiveAmount string
Amount of quote receive currency that the quoteAccount expects to receive (in fractional units)
baseReceiveCurrency string
Base offchain currency of currency pair that the baseAccount expects to receive (eg. for trading pair BTC/USD, ofusd would be "baseReceiveCurrency"). Only required for agency settlement.
quoteReceiveCurrency string
Quote offchain currency of currency pair that the quoteAccount expects to receive. (eg. for trading pair BTC/USD, ofcbtc would be "quoteReceiveCurrency"). Only required for agency settlement.
costBasis string
Price of base currency per quote currency (optional field set by customer for their own use.)
costBasisCurrency string
Fiat currency used for "costBasis"
externalId string
Trade ID used in your system

200 Response

id string <uuid>
Settlement ID
Example: 5be99b8a-6eb5-4ed6-b135-894bb22c5454
requesterAccountId string
Trading account that is requesting settlement
Example: 5caed8b6e9abd8e865e3a942a74967d3
requesterAccountName string
Name of trading account that is requesting settlement
Example: Enterprise A Trading Account
status string
The current status of the settlement
Allowed values: canceled pending rejected settled failed
Example: pending
type string
The current status of the settlement
Allowed values: direct agency
Example: direct
affirmations array[Affirmation]
id string <uuid>
Affirmation ID
counterpartyAccountId string <uuid>
The account ID of the counterparty
counterpartyName string
The name of the counterparty's trading account
partyAccountId string <uuid>
Trading account that the Affirmation belongs to
status string
The current status of the affirmation
Allowed values: pending overdue rejected affirmed failed canceled
Example: pending
settlement string <uuid>
Settlement ID associated with this Affirmation
lock Lock
Assets locked up on a trading account
Example: {"id":"b44616d8-142d-41d7-8037-b6b08f65919f","accountId":"5ca309aa4b389efa274c7fbc8cfc1c72","status":"active","amount":"1000000","currency":"USD","createdAt":{}}
payload string
Stringified JSON of trade payload. If the Affirmation signature is not found, then "payload" is automatically calculated and populated here
signature string
The "payload" cryptographically signed by trading account. Used to authorize the movement of funds
createdAt string <date-time>
ISO date string
expireAt string <date-time>
ISO date string
expireAt string <date-time>
ISO date string
finalizedAt string <date-time>
ISO date string
createdAt string <date-time>
ISO date string
trades array[Trade]
id string <uuid>
Trade ID
baseAccountId string required
Trading account ID that is sending base currency
quoteAccountId string required
Trading account ID that is sending quote currency
status string required
The status of the trade
Allowed values: pending overdue rejected affirmed settled failed
Example: pending
timestamp string <date-time>required
ISO date string
baseAmount string required
Amount of base currency in fractional units
quoteAmount string required
Amount of quote currency in fractional units
baseCurrency string required
Base offchain currency of currency pair. (eg. for trading pair BTC/USD, ofcbtc would be "baseCurrency")
quoteCurrency string required
Quote offchain currency of currency pair. (eg. for trading pair BTC/USD, ofcusd would be "quoteCurrency")
baseReceiveAmount string
Amount of base receive currency that the baseAccount expects to receive (in fractional units)
quoteReceiveAmount string
Amount of quote receive currency that the quoteAccount expects to receive (in fractional units)
baseReceiveCurrency string
Base offchain currency of currency pair that the baseAccount expects to receive (eg. for trading pair BTC/USD, ofusd would be "baseReceiveCurrency"). Only required for agency settlement.
quoteReceiveCurrency string
Quote offchain currency of currency pair that the quoteAccount expects to receive. (eg. for trading pair BTC/USD, ofcbtc would be "quoteReceiveCurrency"). Only required for agency settlement.
costBasis string
Price of base currency per quote currency (optional field set by customer for their own use.)
costBasisCurrency string
Fiat currency used for "costBasis"
externalId string
Trade ID used in your system

400 Response

error string required
Human-readable error message
errorName string required
Immutable error code for API integration
reqId string required
Client request id