Comment on page

Settlement (Trading)

Learn how to execute settlements in your Arc application.
The settlement operation allows for the trade of assets between two users. The action can be executed via a single API call, with support for all assets enabled in your application. The details, from both users, must be signed and subsequently submitted by your application to Arc.
Only assets enabled in your application can be used for settlement operations.
The following steps illustrate the typical flow of a settlement operation in Arc:
  1. 1.
    Application has two users that want to settle assets. For each user, the Application needs to compute a signable payload.
  2. 2.
    Each user signs their settlement order based on the signable payload and submits a POST request to Application's endpoint to execute the settlement.
  3. 3.
    The Application receives the settlement request from the users and forwards it to the /api/v1/settlements endpoint of the Arc API.
  4. 4.
    Arc receives the settlement request from the application, performs validation actions, and if the validation passes, updates the balances for the users involved in the settlement.
  5. 5.
    The Application then sends a response back to the users indicating that the settlement was successful.

Get signable payload

To generate the required settlement signature for each user, first you need to get the messageHash that the users need to sign with their private STARK key. In order to do this, you can use StarkEx JS crypto SDK, our own SDK in C#.
// init cryptoUtils
const cryptoUtils: ICryptoUtils = new CryptoUtils();
await cryptoUtils.init(message);
// order data
const orderData: OrderDataDto = {
sellQuantizedAmount: '21415926535',
buyQuantizedAmount: '1',
sellVaultChainId: 1,
buyVaultChainId: 2,
expirationTimestamp: 123123123,
nonce: 123,
assetBuy: '0x123abcafff',
assetSell: '0x123abca123',
Using the StarkEx.Crypto.SDK package:
var transferMessage = new EncodeLimitOrderWithFeesModel
AssetIdSold = sellVault.AssetStarkExId,
AssetIdBought = buyVault.AssetStarkExId,
AssetIdUsedForFees = feesVault.AssetStarkExId,
QuantizedAmountSold = sellAmountQuantized,
QuantizedAmountBought = buyAmountQuantized,
QuantizedAmountUsedForFees = feeAmountQuantized,
Nonce = nonce,
VaultIdUsedForFees = feesVault.VaultChainId,
VaultIdUsedForSelling = sellVault.VaultChainId,
VaultIdUsedForBuying = buyVault.VaultChainId,
ExpirationTimestamp = expirationTimestamp,
var messageHash = target.EncodeLimitOrderWithFees(transferMessage);
# Signing payload hash with StarkWare's Python resources
from .signature import FIELD_PRIME, pedersen_hash
def get_limit_order_msg(
vault_sell: int, vault_buy: int, amount_sell: int, amount_buy: int, token_sell: int,
token_buy: int, nonce: int, expiration_timestamp: int,
hash=pedersen_hash) -> int:
party_a sells amount_sell coins of token_sell from vault_sell.
party_a buys amount_buy coins of token_buy into vault_buy.
assert 0 <= vault_sell < 2**31
assert 0 <= vault_buy < 2**31
assert 0 <= amount_sell < 2**63
assert 0 <= amount_buy < 2**63
assert 0 <= token_sell < FIELD_PRIME
assert 0 <= token_buy < FIELD_PRIME
assert 0 <= nonce < 2**31
assert 0 <= expiration_timestamp < 2**22
instruction_type = 0
return get_msg(
instruction_type, vault_sell, vault_buy, amount_sell, amount_buy, token_sell, token_buy,
nonce, expiration_timestamp, hash=hash)

Sign settlement details

To generate the required signature, asked in the first form under /api/v1/settlements, users should sign the signablePayload with their private STARK key. In order to do this, you can use StarkEx JS crypto SDK, our own SDK in C#.
const signature = cryptoUtils.settlements().signOrder(orderData);
Using the StarkEx.Crypto.SDK package:
var messageHash = "5359c71cf08f394b7eb713532f1a0fcf1dccdf1836b10db2813e6ff6b6548db"
var privateKey = "2dccce1da22003777062ee0870e9881b460a8b7eca276870f57c601f182136c";
var signer = CreateStarkExSigner();
// R: "5f496f6f210b5810b2711c74c15c05244dad43d18ecbbdbe6ed55584bc3b0a2",
// S: "4e8657b153787f741a67c0666bad6426c3741b478c8eaa3155196fc571416f3"
var signature = signer.SignMessage(messageHash, privateKey);
# Signing payload hash with StarkWare's Python resources
from .signature import sign
r, s = sign(transfer_msg, private_key)

Submit settlement request

To settle assets between two users, applications can issue an HTTP POST request /api/v1/settlements with the following body:
Submit Settlement