POST/api/v1/add-to-contract-whitelist

Add an address to a token whitelist

Adds an address to a token's approved-destination list, returning a transaction proposal that the owning vault's signers approve before the change takes effect on-chain.

AccessRequires a permission in the workspaceMANAGE_WORKSPACE

A token whitelist is enforced on-chain by the token itself: while the whitelist is on, the token cannot be sent to an address that is not on its list. Adding an address is therefore a contract action rather than a saved setting, which is why the response has the same shape as POST /api/v1/call-contract: a psbt_id and a psbt_base64 for the owning vault's signers to approve through POST /api/v1/sign-psbt. The address becomes an approved destination only once the vault's threshold is met and the transaction is broadcast.

Whitelisting is per token, so an address approved for one token is not approved for another. The Address Book is a separate, workspace-level list of named addresses, and saving an address there with POST /api/v1/add-whitelist-address does not approve it for any token. Whitelist Management and Managing whitelisted addresses describe the same two layers as operators see them. Note the field names on this endpoint: it takes workspace_uid and wallet_uid, where the token endpoints take workspace_id and wallet_id.

A whitelist change is an on-chain action

When the last required approval arrives, the change is finalised and submitted to the Bitcoin network automatically. There is no separate confirmation step, and a broadcast transaction cannot be reversed. Check the address, character for character, before you collect approvals.

Body parameters

workspace_uidnumberrequired

The workspace the token belongs to. You must hold MANAGE_WORKSPACE in it. Note the uid suffix, not workspace_id.

wallet_uidstringrequired

The vault that owns the token contract and whose signers approve this change. Note the uid suffix, not wallet_id.

contract_uidnumberrequired

The token whose approved-destination list you are adding to.

address_to_whiteliststringrequired

The Bitcoin address to approve as a destination for this token.

bash

curl -X POST "$SQRL_API/api/v1/add-to-contract-whitelist" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "workspace_uid": 342,
        "wallet_uid": "vault_01HZXB2K7P",
        "contract_uid": 512,
        "address_to_whitelist": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h"
      }'

const res = await fetch(
  `${process.env.SQRL_API}/api/v1/add-to-contract-whitelist`,
  {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.SQRL_TOKEN}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      workspace_uid: 342,
      wallet_uid: "vault_01HZXB2K7P",
      contract_uid: 512,
      address_to_whitelist: "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
    }),
  },
);
const { call_uid, psbt_id, psbt_base64 } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/add-to-contract-whitelist", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "workspace_uid": 342,
        "wallet_uid": "vault_01HZXB2K7P",
        "contract_uid": 512,
        "address_to_whitelist": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
    }))
    .send()
    .await?;

Response200 OK

{
"call_uid": 8871,
"call_id": "call_01HZXF3T7K",
"payload_hash": "c4e8a1f7…2db",
"psbt_id": "psbt_01HZXC9F4R",
"psbt_base64": "cHNidP8BAHECAAAAAf…AAAA"
}

#What happens next

The owning vault's signers approve the returned proposal with POST /api/v1/sign-psbt, and the change is finalised and submitted once the threshold is met. Follow it on GET /api/v1/contract-calls, where the call_uid above appears as UID, and read the resulting list with GET /api/v1/get-workspace-whitelist.

Was this page helpful?