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" } ] }