CoKeeps Docs

Appearance

JavaScript SDK API ​

Tools ​

NOTE

If Node.js is the chosen environment, a dedicated Node.js SDK can be made available for utilizing this method.

Arithmetic ​

This tool performs safe arithmetic operations. Ensure that you provide values as strings rather than integers or floating-point numbers to accurately maintain their values when used as variables.

Use + for addition, - for subtraction, x for multiplication, and / for division.

javascript
const operation = "+"; // Addition
const a = "5.2231";
const b = "6";
const decimal = 4;
const result = CKSDK.tool.arithmetic(operation, a, b, decimal);

NOTE

The result will always be a string.

Decimal to Integer ​

This tool converts decimals to integers safely. You can optionally output the value in BigInt format by passing an additional variable into the function; otherwise, it will always output the value as a string.

javascript
const value = "5.2231";
const decimal = 4;
const outputBigInt = true;
const result = CKSDK.tool.dec_to_int(value, decimal, outputBigInt);

Integer to Decimal ​

This tool converts integers to decimals safely.

javascript
const value = "52231";
const decimal = 4;
const result = CKSDK.tool.int_to_dec(value, decimal);

NOTE

The result will always be a string.

Pagination filters ​

This SDK API provides options for performing pagination queries.

NOTE

If Node.js is the chosen environment, a dedicated Node.js SDK can be made available for utilizing this method.

Options include:

  • users
  • destinations
  • travelRules
  • ledger
  • pool
  • accounts
  • transactions
    • transfer
    • sweepDeposit
    • sweepWithdrawal
    • sweepGasStation
    • sweepSignerWalletBase
    • gasStation
    • rebalance

Here's an example using the transactions -> transfer filter:

javascript
const params = CKSDK.pagination.filters.transactions.transfer;
console.log(params);

Here's an example output of the above:

json
[
    // -- Snip --
    {
        "key": "tid",
        "type": "string",
        "text": "Tx ID",
        "value": null,
    },
    {
        "key": "uid",
        "type": "string",
        "text": "UID",
        "value": null,
    },
    // -- Snip --
]

Here are the value types:

  • string: Represents a string value.
  • Date: Denotes a Date object. Eg. new Date('now').
  • boolean: Represents either true or false.
  • number: Denotes a numerical value. Eg. !isNaN("5.2").

Actions ​

NOTE

This scope covers both signer and admin roles. admin cannot approve their own actions and must be approved by other admin.

Set Destination Address ​

In the transfer procedure, users are required to provide the destination address for their transaction transfer recipient. Typically, this destination address must undergo approval before the transfer can proceed.

javascript
const types = [
  { text: "Self Hosted", value: "self-hosted" },
  { text: "Provider (Exchange / Custodian)", value: "provider" },
];

// Returns a Promise
CKSDK.action.destination({
    chain_id: "bitcoin",
    address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    // For Travel Rule
    name: "Ahmad Damha",
    country: "Malaysia",
    caddress: "1, Jalan 2, Taman Tiga, 53100, Kuala Lumpur, Malaysia",
    contact: "600-1122334455",
    email: "[email protected]",
    reference: "This is a test",
    type: types[0].value, // "self-hosted"
    typeName: "Ledger Hardware Wallet",
    addressSignature: "637b9be6f950135997306976c6dea4d1bc956c17b985194ee7398697949e8b07798eba71eb37becca027ceacd55c1ebc67131a98bf0f30fa8b6ae9c7df42ae0762326431356331376431663263646530343564373331336461616666396437663437613962386364343336373133313661663430633734663330613931643539",
    addressSignatureInput: ""
});

For the "Self Hosted" type, you must define the following variables:

  • addressSignature: This is the signature digest of the message signing of the address value using the private key for proof of address ownership. WalletConnect can be used to sign the address as a message.

  • addressSignatureInput: This is the Public Key for Ripple or Solana SPL-Token only.

NOTE

Only one destination address can be set at a time per chain.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "id": "66c56b3e66a0c500120d9237",
  }
}

Retrieve Deposit Address ​

If your platform involves accepting coins or tokens as part of your product or service, such as for digital asset trading, you'll need a deposit address for each user to receive incoming funding.

NOTE

The address is unique for each chain and changes with every credential reset.

javascript
// Returns a Promise
CKSDK.action.generate_deposit({
  chain_id: "ethereum",
  smartAccount: false, // Optional
  deterministicForwarder: "<address_of_smart_contract>" // Optional and only when `smartAccount` is `false`
});

For admin with the permission to sweep, deposits can be transferred into a multi-signature transaction assigned to receive them.

A Smart Account is designed exclusively for EVM-based blockchains, where a Smart Contract represents the account instead of an Externally Owned Account (EOA) controlled by a keypair. This setup offers the flexibility to add features, such as automatically rejecting non-whitelisted incoming transactions. However, it requires deploying the account individually on each blockchain you wish to support, each with its own unique address. This can lead to issues with incorrect transfers becoming unrecoverable. For instance, if USDT is transferred on layer 1 instead of the expected layer 2, the funds cannot be easily recovered—an issue that does not arise with EOAs.

For EVM-based blockchains, a specialised smart contract known as a "deterministic forwarder" can be deployed to manage deposits. This contract can automatically forward received native coins, eliminating the need for manual sweeping.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "address": "0x391EF99987f60CE0cf3382FE00295B0c1e8DE6b5"
  }
}

Retrieve Signer Wallet Address ​

javascript
// Returns a Promise
CKSDK.action.generate_wallet({
    chain_id: "solana",
    label: "Account 1",
    smartAccount: false, // Optional
    message: "A message to sign for proof of ownership" // Optional
});

Your system should also maintain a record of all the labels created by your users, as each label corresponds to a specific address generated deterministically.

The Smart Account is similar to the Deposit Address functionality.

If a message value is provided, the wallet will attempt to sign the message using its private key. Exercise caution when exposing this feature to your users, as it may inadvertently sign a transaction that was not intended.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "address": "9oZ3kPXx1wmnBuDMqiiyKBFt1KKMVT1gPE92N243dfMj",
      "signature": "4923391799a54860d7408aa8b889e126a3fb1af51ba17474d627af35c53f183bf8c7b4e2ea528cc2702afa6646f131eeaa525b5a2194a50002097e2aa1f53903"
  }
}

Transfer Transaction ​

javascript
// Returns a Promise
CKSDK.action.transfer({
  chain_id: "solana",
  from: "AS1yfbX6dx9dJd8fiey3uc22anb6KGZz6USSB8zmGW92",
  to: "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp", // Optional
  amount: "0.5",
  memo: "This is a test",
  reference_id: "TICKET-123",
  estimateFee: false // Optional
});

The from field represents the address of the user's Signer Wallet or a Withdrawal account.

The to field is required for Signer Wallet or Withdrawal account and do not require approval. For Withdrawal, the value must match your destinations in the Read endpoint.

The amount is a string of decimals and it should not exceed the limits specified by your Read endpoint.

The memo field is limited to 256 characters.

The reference_id is your system-generated reference ID for this transaction.

The estimateFee is a boolean flag that, when set, returns the estimated transaction cost without executing the transaction.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "tid": "66c56b0d66a0c500120d9234"
  }
}

Smart Contract Transaction ​

NOTE

This method doesn't immediately execute the transaction and may undergo stages of approval depending on your setup.

IMPORTANT

For ERC-20 or SPL-Token Token transfer, please use the Transfer Transaction API mentioned previously.

javascript
// Returns a Promise
CKSDK.action.interact({
  chain_id: "ethereum",
  from: "0x18682333780a7a2FeBBD0F7Bf6EAb9d37Ae16bFe",
  address: "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
  method: "borrow",
  methodArgs: [ "12050" ],
  reference_id: "TICKET-124",
  estimateFee: false, // Optional
  target_chain_id: false // Optional
});

The from field represents the address of the user's Signer Wallet or Deposit.

The address field represents the address of the smart contract to interact with. This smart contract must already be approved by the organisation via the Client Administration platform.

The method and methodArgs can be obtained from the Back-End REST API Smart Contract Lookup Interface section.

The reference_id is your system-generated reference ID for this transaction.

The estimateFee is a boolean flag that, when set, returns the estimated transaction cost without executing the transaction.

The target_chain_id is utilized to recover transfers made to a token deposit address on the wrong network.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "tid": "66d48fe2ebb3b700115fe55b"
  }
}

Omnibus Withdrawal ​

NOTE

This method doesn't immediately execute the transaction and may undergo stages of approval depending on your setup.

javascript
// Returns a Promise
CKSDK.action.omnibus_withdraw({
  chain_id: "solana",
  amount: "1000",
  memo: "Test withdraw from Omnibus account",
  reference_id: "TICKET-125"
});

The maximum amount value should be the balance of the user's Dynamic Ledger or any value defined by your back-end Read endpoint.

The memo field is limited to 256 characters.

The reference_id is your system-generated reference ID for this transaction.

The recipient of a withdrawal request would be the address value defined in the Set Destination Address action mentioned previously.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "id": "66c56d6666a0c500120d923b"
  }
}

Decisions ​

NOTE

This scope is exclusive to the admin role. admin cannot approve their own actions and must be approved by other admin.

Approve / Reject Destination Address ​

NOTE

The decision made for the destination address will automatically apply to any attached travel rule information.

javascript
const decisions = [
  { text: "Approve", value: "approve" },
  { text: "Reject", value: "reject" },
];

// Returns a Promise
CKSDK.decide.destination({
  _id: "<destination_id>",
  decision: decisions[0].value, // "approve"
  remark: "Additional information to include",
});

The _id represents the Destination ID obtained from the Back-End REST API Information List Destinations.

The remark field is required for the reject decision.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "id": "66c5338caf2057001226d679"
  }
}

Approve / Reject Travel Rule ​

javascript
const decisions = [
  { text: "Approve", value: "approve" },
  { text: "Reject", value: "reject" },
];

// Returns a Promise
CKSDK.decide.travel_rule({
  _id: "<travel_rule_id>",
  decision: decisions[0].value,
  remark: "Additional information to include",
});

The _id represents the Travel Rule ID obtained from the Back-End REST API Information List Travel Rules.

The remark field is required for the reject decision.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "id": "66b974505e39400012dabd34"
  }
}

Approve / Reject Transaction Request ​

javascript
const decisions = [
  { text: "Approve", value: "approve" },
  { text: "Reject", value: "reject" },
];

// Returns a Promise
CKSDK.decide.transaction_request({
  _id: "<tx_pool_id>",
  from: "AS1yfbX6dx9dJd8fiey3uc22anb6KGZz6USSB8zmGW92", // Optional
  decision: decisions[0].value,
  remark: "Additional information to include",
});

The _id represents the Dynamic Transaction Pool ID obtained from the Back-End REST API Dynamic Transaction Pool List Transactions.

The value for the from field is specifically applicable to the Omnibus Withdrawal procedure, where it can be retrieved from the Back-End REST API Dynamic Transaction Pool Retrieve Integrated Accounts.

The remark field is required for the reject decision.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "id": "66c56d6666a0c500120d923b"
  }
}

Management ​

NOTE

This section pertains exclusively to admin with sweep permissions.

All sweep or re-balance actions are subject to approval by other admin who did not initiate the request.

The destination for sweeping actions will be the designated Multi-Signature address for holding funds.

Sweep Deposits ​

javascript
// Returns a Promise
CKSDK.management.sweep_deposits({
  chain_id: "litecoin",
  to: "QXgcRFDWAXbj7QQ7VdZC9vC6U1LUqy5yU9",
  uids: [ "c80df78a-95ef-4717-8c0d-081fcb352994" ], // Optional
  baseChain: false, // Optional
  minimumThreshold: false, // Optional
  target_chain_id: false // Optional
});

The to field is the one or more sweep destination addresses that have been configured.

The uids field is an array of specific UUIDs representing the collective deposits you wish to sweep. If not provided, the operation will sweep everything from deposit addresses with a balance, which is the common scenario.

The baseChain field is a boolean flag that, when set, will sweep the native currency if the balance exceeds the dust threshold or the Gas Station funding minimum deposit.

The minimumThreshold field is a decimal number in string format that, when set, will ignore any deposit balances equal to or below the threshold value.

The target_chain_id is utilized to sweep the network coin balance that was utilized to recover tokens deposited to an incorrect network. Entry in uids must be provided.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "processing": [
          // -- Snip --
          {
            "address": "QgDYu6CGSgz8cbw6VjmLEvQM6UMHKWqRbd",
            "uid": "66b89a8d3f5a710012eb6e2c",
            "tid": "66b960f97a6a430012ead003",
            "error": false
          },
          // -- Snip --
      ]
  }
}

Sweep Withdrawal ​

This method is exclusively used to transfer the entire balance from a Withdrawal account to a Holding account, unlike the Transfer Transaction, which can only send funds to approved destinations. Please note that a dust amount may still remain in the balance.

javascript
// Returns a Promise
CKSDK.management.sweep_withdrawal({
  chain_id: "litecoin",
  from: "QQ4fnSJPWxBPC4RPH4U8J9ucgFvecqvbBK",
  to: "QXgcRFDWAXbj7QQ7VdZC9vC6U1LUqy5yU9",
  baseChain: false // Optional
});

The to field is the one or more Holding addresses that have been configured.

The from field represents the Withdrawal account address to sweep from.

The baseChain field is a boolean flag that, when set, will sweep the native currency if the balance exceeds the dust threshold or the Gas Station funding minimum deposit. If the Withdrawal account is a Multi-Signature account, it will also sweep the member balance.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "processing": [
          // -- Snip --
          {
            "address": "QQ4fnSJPWxBPC4RPH4U8J9ucgFvecqvbBK",
            "tid": "66b971484fec6500121738ff",
            "error": false
          },
          // -- Snip --
      ]
  }
}

Sweep Gas Station ​

This method allows you to clear the balance of a Gas Station account and transfer it to a Holding account. Ensure that another Gas Station is active if there are addresses that still need automatic funding for gas payments.

javascript
// Returns a Promise
CKSDK.management.sweep_gas_station({
  chain_id: "optimism",
  from: "0xb43ddb4c9D42c05Bbcc237BD8d1C74DDD44710aD",
  to: "0x54105432f2b0caeb3AD7119696ED5B14c2e1C1D3"
});

The to field is the one or more Holding addresses that have been configured.

The from field represents the Gas Station account address to sweep from.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "tid": "66d4a1c1ebb3b700115fe55e"
  }
}

Sweep Signer Wallet Base ​

This method allows you to clear the funded base balance of Signer Wallets that do not have any token balance.

javascript
// Returns a Promise
CKSDK.management.sweep_signer_wallet_bases({
  chain_id: "usdt",
  to: "0xF089B217705cf3B9aDFF4757171F72318554820b",
  uids: [ "c80df78a-95ef-4717-8c0d-081fcb352994" ], // Optional
});

The to field is the one or more sweep destination addresses that have been configured.

The uids field is an array of specific UUIDs representing the collective signer wallets you wish to sweep. If not provided, the operation will sweep everything from signer wallet addresses base balances, which is the common scenario.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "processing": [
          // -- Snip --
          {
            "address": "0x49d0A29FAa7F36161740f0A046e0e976A918C8CE",
            "tid": "66c5b16d60e4f50012f15d7c",
            "error": false
          },
          // -- Snip --
      ]
  }
}

Re-balance ​

javascript
// Returns a Promise
CKSDK.management.rebalance({
  chain_id: "solana",
  from: "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp",
  to: "38PBWTJJEqCXHQhtRDs3gmsWY4Vtq87arhmTkm5UcSen",
  amount: "70:30", // or "15.663" SOL
  execute: false // Default
});

The from and to fields represent either a Withdrawal or Holding account address configured for re-balancing between these accounts.

The amount field must be a string that can be represented either as a fixed decimal amount or as a ratio. A ratio value is represented as from_percentage:to_percentage. For example, if the combined balance of the "from" and "to" accounts is 1,000 and the ratio is "30:70", the rebalance procedure will result in the "from" account having a new balance of 300 and the "to" account having a balance of 700.

The execute field is a boolean flag. By default, it returns the summary of the rebalance. If set to true, it will execute the rebalance procedure.

Example response:

json
{
  "success": true,
  "message": "OK",
  "rdata": {
      "tid": "66b8a2c61f071a0012dc03f3",
      "from": "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp",
      "to": "38PBWTJJEqCXHQhtRDs3gmsWY4Vtq87arhmTkm5UcSen",
      "holdingAddress": "38PBWTJJEqCXHQhtRDs3gmsWY4Vtq87arhmTkm5UcSen", 
      "withdrawalAddress": "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp",
      "error": false
  }
}

Copyright © 2024 CoKeeps Sdn Bhd