Off Exchange Settlements

Copper will add a new section called Delegate funds, where clients can transfer part of their funds to the supported exchange.
Suppose a client has 1000 BTC on his portfolio in Copper account.
From the Delegate funds section client can transfer BTC to the exchange.

Copper will then call the exchange’s API /add-funds with specified parameters:

 + POST [exchange-api-endpoint]/add-funds
    
 + Headers
   Authorization: Any Auth Scheme on your side
    
 + Request
   {
     "requestId": "uniq-idempotency-key",               // random uniq string
     "clientAccountId": "client-exchange-account-id",   // string
     "amount": "200.0",                                 // BigDecimal saved in JSON as string
     "currency": "BTC"
   }

Responses:

`200 OK`	ok
`200 OK`	requestId already exist and request params are the same (duplicate)
`400 Bad Request`	this requestId already exists but request params are not the same
`409 Conflict`	can’t process request (balance not available, etc.)
`4`, `5`	any other error (timeout, service not available, etc.) — request will be retried after some delay

You can use you own authorization scheme, or implement something like this /getting-started/authentication/

Copper is able to call API, which will return funds back

 + POST [exchange-api-endpoint]/remove-funds
    
 + Headers
   Authorization: Any Auth Scheme

 + Request
   {
     "requestId": "uniq-idempotency-key",              // random uniq string
     "clientAccountId": "client-exchange-account-id",  // string
     "amount": "50.0",                                 // BigDecimal saved in JSON as string
     "currency": "BTC"
   }

Responses:

`200 OK`	ok
`200 OK`	requestId already exist and request params are the same (duplicate)
`400 Bad Request`	this requestId already exists but request params are not the same
`409 Conflict`	can’t process request (balance not available, etc.)
`4`, `5`	any other error (timeout, service not available, etc.) — request will be retried after some delay

When the position is closed, exchange should send a request to the Copper for settlement.

 + POST https://api.copper.co/platform/orders
    
 + Headers
   Authorization: ApiKey xxxx   // see [API Authorization](/getting-started/authentication/)
   X-Signature: xxx
   X-Timestamp: xxx
    
 + Request
   {
     "externalOrderId": "exchange-uniq-order-id",
     "portfolioId": "exchange-portfolio-id",   // exchange's account id in the Copper Platform, to which BTC will be deposited
     "orderType": "buy",     // or "sell"
     "limitType": "off-exchange",
     "baseCurrency": "BTC",
     "quoteCurrency": "USD",  // optional, leave it empty for "clearing" order, when you just move funds from or to client
     "amount": "10.0",
     "price": "7650.0",      // optional
     "clientAccountId": "client-exchange-account-id"
   }

When this API method is called, Copper will check client-exchange-account-id has enough locked assets in favor of the exchange, debit funds from the client and top up exchange balance.

Settlement examples:

Send 10 BTC to client

{
  "externalOrderId": "3B378E6D-C36F-4209-96A7-09BD432D2536",
  "portfolioId": "exchange-portfolio-id", 
  "orderType": "sell",
  "limitType": "off-exchange",
  "baseCurrency": "BTC",
  "amount": "10.0",
  "clientAccountId": "client-exchange-account-id"
}

Get 7 BTC from client

{
  "externalOrderId": "0197A4D6-65F1-40E7-BC98-1D502AEC2AE4",
  "portfolioId": "exchange-portfolio-id", 
  "orderType": "buy",
  "limitType": "off-exchange",
  "baseCurrency": "BTC",
  "amount": "7.0",
  "clientAccountId": "client-exchange-account-id"
}

Send 2 BTC to client and get 12000 USD back

{
  "externalOrderId": "7784898F-B1DA-411E-A0E5-988084EB1281",
  "portfolioId": "exchange-portfolio-id", 
  "orderType": "sell",
  "limitType": "off-exchange",
  "baseCurrency": "BTC",
  "quoteCurrency": "USD", 
  "amount": "2.0",
  "price": "6000.0", 
  "clientAccountId": "client-exchange-account-id"
}