POST/api/v1/call-contract

Perform a token action

Performs any action on a token, from transfer, mint, and burn to pausing, whitelist changes, and ownership transfer, checking the permission and spending limits the action requires and returning a proposal for the vault's signers to approve.

AccessRequires a permission in the workspaceMANAGE_WORKSPACEPAYMENT_INIT

A single endpoint performs every token action. function_name selects the action and args carries its arguments, in order. The permission you need depends on the action you ask for, and so do the limits that apply: a transfer must be within both the member's role spending limit and the vault's spending limit, while mint and burn must be within the vault's spending limit.

Every action here is anchored to a Bitcoin transaction, so the response returns a psbt_id and a psbt_base64 for the vault's signers to approve through POST /api/v1/sign-psbt. Nothing reaches the network until the vault's threshold is met.

#Actions and permissions

Action	What it does	Who can use it
`transfer`	Send tokens to another address.	Initiate Payment. The amount must be within both the member's role spending limit and the vault's spending limit.
`mint`	Create new tokens.	Manage Workspace. The amount must be within the vault's spending limit.
`burn`	Destroy tokens.	Manage Workspace. The amount must be within the vault's spending limit.
`pause`, `unpause`	Halt or resume all token activity.	Manage Workspace
`transfer_ownership`	Hand the token's ownership to another party.	Manage Workspace
`enable_whitelist`, `disable_whitelist`	Turn the token's destination whitelist on or off.	Manage Workspace
`add_to_whitelist`, `remove_from_whitelist`	Edit the token's approved-destination list.	Manage Workspace
`init`	First-time initialisation after deployment. Allowed only once the deployment has at least one Bitcoin confirmation.	Manage Workspace

Actions are final once the threshold is met

When the last required approval arrives, the transaction is finalised and submitted to the Bitcoin network automatically. There is no separate confirmation step, and a transaction that has been broadcast cannot be reversed. Check the arguments, in particular the destination address and the raw-unit amount, before you collect approvals.

Body parameters

contract_uidnumberrequired

The token to act on, as returned by create-token or contracts.

wallet_idstringrequired

The vault that holds the token and whose signers approve this action.

function_namestringrequired

The action to perform. One of transfer, mint, burn, pause, unpause, transfer_ownership, enable_whitelist, disable_whitelist, add_to_whitelist, remove_from_whitelist, or init.

argsobject[]required

The action's arguments, in order, each one carrying its own type. For transfer, mint, and burn, args[0] is the address and args[1] is the amount.

typestringrequired

The argument's type. Either str for a text value such as an address, or int for a whole number such as an amount.

valuestringrequired

The argument's value, sent as the JSON type that type names: a string when type is str, a number when type is int. Amounts are raw units, already scaled by the token's decimals.

recipientsstring[]optional

Addresses to record on the transaction proposal that carries this action.

workspace_idnumberrequired

The workspace the token and vault belong to. You must hold the permission the requested action needs in it.

prioritystringoptional

Fee priority for the transaction. Either low, medium, or high, which sets the miner fee to pay and therefore how quickly the transaction should confirm. A standard fee is used when omitted.

bash

curl -X POST "$SQRL_API/api/v1/call-contract" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "contract_uid": 512,
        "wallet_id": "vault_01HZXB2K7P",
        "function_name": "transfer",
        "args": [
          { "type": "str", "value": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h" },
          { "type": "int", "value": 150000 }
        ],
        "recipients": ["bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h"],
        "workspace_id": 342,
        "priority": "medium"
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/call-contract`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    contract_uid: 512,
    wallet_id: "vault_01HZXB2K7P",
    function_name: "transfer",
    args: [
      { type: "str", value: "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h" },
      { type: "int", value: 150000 },
    ],
    recipients: ["bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h"],
    workspace_id: 342,
    priority: "medium",
  }),
});
const { call_uid, psbt_id, psbt_base64 } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/call-contract", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "contract_uid": 512,
        "wallet_id": "vault_01HZXB2K7P",
        "function_name": "transfer",
        "args": [
            { "type": "str", "value": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h" },
            { "type": "int", "value": 150000 }
        ],
        "recipients": ["bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h"],
        "workspace_id": 342,
        "priority": "medium",
    }))
    .send()
    .await?;

Response200 OK

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

#What happens next

The vault's signers approve the returned proposal with POST /api/v1/sign-psbt, and the action 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 use POST /api/v1/contract-calls/resubmit if the action stalls before it reaches the network.

Was this page helpful?