Link

Off Exchange Settlements

  1. Copper will add a new section called Delegate funds, where clients can transfer part of their funds to the supported exchange.

  2. Suppose a client has 1000 BTC on his portfolio in Copper account.

  3. From the Delegate funds section client can transfer BTC to the exchange.

  4. 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/

  1. 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
  2. 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:

  1. 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"
    }
    
  2. 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"
    }
    
  3. 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"
    }