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, UUID for example
     "clientAccountId": "client-exchange-account-id",   // string
     "amount": "200.0",                                 // BigDecimal saved in JSON as string
     "currency": "BTC"
   }

Example:

 curl -XPOST https://api.example-exchange.com/api/add-funds -d '\
   { \
     "requestId": "44422FB2-6546-4D0C-BDBB-1E1C3AA92801", \
     "clientAccountId": "xRtk356rtee9q", \
     "amount": "3.001345", \
     "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",
     "description": "Any text description here"  // optional
   }
   
+ Response 201 Created
  {
    "orderId": "order-id",
    "externalOrderId": "exchange-uniq-order-id",
    "status": "executed",
    "orderType": "buy",
    "portfolioId": "exchange-portfolio-id",
    "portfolioType": "trading",
    "amount": "0.00000008",
    "baseCurrency": "BTC",
    "mainCurrency": "BTC",
    "quoteCurrency": "USD",
    "limitType": "off-exchange",
    "priceLimit": "0",
    "extra": {
      "counterpartyPortfolioId": "counterparty-portfolio-id",
      "counterpartyOrderId": "counterparty-order-id",
      "counterpartyClientAccountId": "client-exchange-account-id",
      "balanceSnapshot": "0.06370536"
    },
    "createdBy": "createdBy",
    "organizationId": "organizationId",
    "createdAt": "1600691640160",
    "updatedAt": "1600691640355",
    "terminatedAt": "1600691640291"
  }

When this API method is being 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"
 }

Get all managed funds, which delegated to exchange from all clients at this time

 + GET /platform/managed-funds 
    
 + Response 200 OK
   {
     "managedFunds": [
       {
         "currency": "BTC",
         "amount": "3.00456",
         "portfolioId": "EB33434A-D8DB-4E8C-8F8A-58A867108DE9",   // client's portfolio
         "organizationId": "MYORG1",            // client's organization
         "delegatedOrganizationId": "DRBT",  
         "clientAccountId": "777" 
       },
       {
         "currency": "LTC",
         "amount": "14.01",
         "portfolioId": "EB33434A-D8DB-4E8C-8F8A-58A867108DE9",
         "organizationId": "OTHERORG2",
         "delegatedOrganizationId": "DRBT",
         "clientAccountId": "74635282"
       }
     ]
   }

Get managed funds transactions

 + GET /platform/managed-funds/transactions 
    
 + Response 200 OK
   {
     "managedFundsTransactions": [
       {
         "transactionId": "5834944",
         "currency": "BTC",
         "amount": "-0.0000001",
         "organizationId": "client-organization",
         "delegatedOrganizationId": "exchange-organization-id",
         "clientAccountId": "client-account-id",
         "createdAt": "1603384189501"
       }
     ]
   }