Claim Project Credential

Claiming a project credential is the final step in a contributor's task lifecycle. After a manager accepts a task submission, the contributor claims their credential and reward. This transaction burns the contributor-state token, stores the credential hash in global state, refunds the contributor-state deposit, and pays a small protocol fee to the instance treasury. The contributor typically receives a net gain from the deposit refund.

Summary

Property	Value
System	Project
Role	Contributor
Type Key	`project_credential_claim`
Build Endpoint	`POST /api/v2/tx/project/contributor/credential/claim`
DB Sync	Yes
Service Fee	1 ADA (to instance treasury)
Est. Wallet Cost	~-13 ADA (net gain)

The estimated wallet cost is a net gain for the contributor: the contributor-state deposit refund (~14.5 ADA) minus the transaction fee (~0.35 ADA) minus the protocol fee (1.0 ADA) results in approximately 13 ADA returned to the contributor's wallet. On confirmation, the task commitment status is set to REWARDED in the database.

Build Transaction

Endpoint

POST /api/v2/tx/project/contributor/credential/claim

Request Body

{
  "alias": "contributor1",
  "project_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "contributor_state_id": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
  "initiator_data": {
    "usedAddresses": ["addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x"],
    "changeAddress": "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x"
  }
}

Field	Type	Required	Description
`alias`	`string` (Alias)	Yes	The contributor's access token alias. Must have an accepted task in this project.
`project_id`	`string` (GYMintingPolicyId)	Yes	56-character hex policy ID returned from project creation.
`contributor_state_id`	`string` (GYMintingPolicyId)	Yes	The contributor-state policy ID for the project.
`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": "project_credential_claim",
  "metadata": {
    "task_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
}

This is one of only 3 transaction types that require registration metadata. The task_hash in metadata identifies which task's credential is being claimed. On confirmation, the state machine sets the task commitment status to REWARDED in the database.

No specific off-chain endpoints are associated with credential claims. The credential hash is stored in global state on-chain, and the database records the REWARDED status.

Example: Full Lifecycle

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

// 1. Build
const buildRes = await fetch(`${API_URL}/api/v2/tx/project/contributor/credential/claim`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY,
    "Authorization": `Bearer ${userJwt}`,
  },
  body: JSON.stringify({
    alias: "contributor1",
    project_id: projectId,
    contributor_state_id: contributorStateId,
    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 (requires metadata)
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: "project_credential_claim",
    metadata: { task_hash: taskHash },
  }),
});

// 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();
});