POST/api/v1/create-token

Create a token

Records a new token with its supply, decimals, and whitelist setting, then builds its deployment transaction from the owning vault and returns a proposal for that vault's signers to approve.

AccessRequires a permission in the workspaceMANAGE_WORKSPACE

Two things happen on this call: the token is recorded in the workspace, and its deployment starts as a movement from vault_id. Deployment is anchored to a Bitcoin transaction, so the response carries a psbt_id and a psbt_base64 that the vault's signers approve through POST /api/v1/sign-psbt. The vault's M-of-N threshold applies here as it does to any other movement.

Keep the contract_uid the response returns: it identifies the token on every later call, including GET /api/v1/contract and POST /api/v1/call-contract. For the operator walkthrough of the same flow, see Deploying a token.

Supply figures are raw units

total_supply and max_supply are integer strings already scaled by decimals_num. For a token with 2 decimals, five million tokens is "500000000". Scale both figures by the decimals you set on this same call.

Body parameters

token_namestringrequired

Display name for the token, shown wherever the token appears.

tickerstringrequired

Short symbol for the token, for example NGT.

iconstringrequired

URL of the token's icon.

decimals_numnumberrequired

Number of decimal places the token uses. It fixes the size of a raw unit, so the supply figures on this call must already be scaled by it.

total_supplystringrequired

Supply created at deployment. Raw units, already scaled by the token's decimals.

max_supplystringrequired

Upper bound on the tokens that can ever exist. Raw units, already scaled by the token's decimals.

whitelist_enabledbooleanrequired

Whether the token's destination whitelist is enforced. Either true or false.

vault_idstringrequired

The vault that deploys and owns the token. Its signers approve the deployment.

workspace_idnumberrequired

The workspace the token belongs to. You must hold MANAGE_WORKSPACE in it.

networkstringrequired

The Bitcoin network to deploy on. Either mainnet or testnet, matching the network of the workspace in workspace_id.

prioritystringoptional

Fee priority for the deployment 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.

white_list_idsnumber[]optional

Ids of the whitelist entries to attach to the token at deployment.

bash

curl -X POST "$SQRL_API/api/v1/create-token" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "token_name": "Northgate Token",
        "ticker": "NGT",
        "icon": "https://cdn.example.com/tokens/ngt.svg",
        "decimals_num": 2,
        "total_supply": "500000000",
        "max_supply": "1000000000",
        "whitelist_enabled": true,
        "vault_id": "vault_01HZXB2K7P",
        "workspace_id": 342,
        "network": "mainnet",
        "priority": "medium"
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/create-token`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    token_name: "Northgate Token",
    ticker: "NGT",
    icon: "https://cdn.example.com/tokens/ngt.svg",
    decimals_num: 2,
    total_supply: "500000000",
    max_supply: "1000000000",
    whitelist_enabled: true,
    vault_id: "vault_01HZXB2K7P",
    workspace_id: 342,
    network: "mainnet",
    priority: "medium",
  }),
});
const { contract_uid, psbt_id, psbt_base64 } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/create-token", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "token_name": "Northgate Token",
        "ticker": "NGT",
        "icon": "https://cdn.example.com/tokens/ngt.svg",
        "decimals_num": 2,
        "total_supply": "500000000",
        "max_supply": "1000000000",
        "whitelist_enabled": true,
        "vault_id": "vault_01HZXB2K7P",
        "workspace_id": 342,
        "network": "mainnet",
        "priority": "medium",
    }))
    .send()
    .await?;

Response200 OK

{
"contract_uid": 512,
"bytecode_hash": "b7f1e2c9…9ac",
"psbt_id": "psbt_01HZXC9F4R",
"psbt_base64": "cHNidP8BAHECAAAAAf…AAAA"
}

#What happens next

Each signer on the vault approves the deployment proposal with POST /api/v1/sign-psbt, and the deployment is finalised and broadcast automatically once the threshold is met. Follow its progress on GET /api/v1/contract, where status moves through the token deployment statuses. Once the deployment has at least one Bitcoin confirmation you can run the init action through POST /api/v1/call-contract.

Was this page helpful?