API integration guide for adding and removing contributors from a project blacklist

Manage Contributor Blacklist

Managing the contributor blacklist allows the project owner to block or unblock specific contributors from participating in the project. Blacklisted contributors cannot commit to tasks or interact with the project on-chain. The blacklist is tracked entirely on-chain with no database sync.

Summary

Property	Value
System	Project
Role	Owner
Type Key	`blacklist_update`
Build Endpoint	`POST /api/v2/tx/project/owner/contributor-blacklist/manage`
DB Sync	No
Service Fee	0 ADA
Est. Wallet Cost	~0.34 ADA

This is one of the lowest-cost transactions in the protocol. The estimated wallet cost is the transaction fee only, with no service fee or additional deposits.

Build Transaction

Endpoint

POST /api/v2/tx/project/owner/contributor-blacklist/manage

Request Body

{
  "alias": "projectowner",
  "project_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "aliases_to_add": ["badactor1"],
  "aliases_to_remove": ["rehabilitated1"],
  "initiator_data": {
    "usedAddresses": ["addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x"],
    "changeAddress": "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x"
  }
}

Field	Type	Required	Description
`alias`	`string` (Alias)	Yes	The owner's access token alias. Only the project owner can manage the blacklist.
`project_id`	`string` (GYMintingPolicyId)	Yes	56-character hex policy ID returned from project creation.
`aliases_to_add`	`string[]` (Alias[])	Yes	Contributor aliases to blacklist. Pass `[]` if only removing from the blacklist.
`aliases_to_remove`	`string[]` (Alias[])	Yes	Contributor aliases to un-blacklist. Pass `[]` if only adding to the blacklist.
`initiator_data`	`WalletData`	No	Object containing `usedAddresses` (string[]) and `changeAddress` (string). If omitted, the Gateway resolves wallet data from the authenticated session.

Response

{
  "unsigned_tx": "84a800..."
}

The response contains the unsigned transaction CBOR, ready for the user's wallet to sign.

Register Transaction

After the user signs and submits the transaction, register it with the state machine:

POST /api/v2/tx/register

{
  "tx_hash": "64-char hex hash from wallet.submitTx()",
  "tx_type": "blacklist_update"
}

No metadata is required. Since the blacklist is tracked on-chain only, the state machine confirms the transaction but does not update the database with blacklist contents.

Endpoint	Description
`GET /api/v2/projects/{project_id}`	Fetch project details; blacklist state is reflected in on-chain data

Example: Full Lifecycle

const API_URL = "https://api.andamio.io";

// 1. Build
const buildRes = await fetch(`${API_URL}/api/v2/tx/project/owner/contributor-blacklist/manage`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY,
    "Authorization": `Bearer ${userJwt}`,
  },
  body: JSON.stringify({
    alias: "projectowner",
    project_id: projectId,
    aliases_to_add: ["badactor1"],
    aliases_to_remove: [],
    initiator_data: {
      usedAddresses: [walletAddress],
      changeAddress: walletAddress,
    },
  }),
});
const { unsigned_tx } = await buildRes.json();

// 2. Sign
const signedTx = await wallet.signTx(unsigned_tx);

// 3. Submit
const txHash = await wallet.submitTx(signedTx);

// 4. Register
await fetch(`${API_URL}/api/v2/tx/register`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY,
    "Authorization": `Bearer ${userJwt}`,
  },
  body: JSON.stringify({
    tx_hash: txHash,
    tx_type: "blacklist_update",
  }),
});

// 5. Monitor (SSE)
const events = new EventSource(
  `${API_URL}/api/v2/tx/stream/${txHash}`
);
events.addEventListener("state_change", (e) => {
  const data = JSON.parse(e.data);
  console.log(`State: ${data.old_state} → ${data.new_state}`);
});
events.addEventListener("complete", (e) => {
  const data = JSON.parse(e.data);
  console.log(`Final: ${data.final_state}`);
  events.close();
});