Andamio Logo
Developer Guides

Transaction Handling

Build, sign, submit, and track Andamio transactions

Transaction Handling

Every transaction follows the same lifecycle: build → sign → submit → register → monitor.

Your app requests a transaction, the user signs, Andamio submits and confirms on-chain, then syncs to the database.

Deep dive: For state transitions, error handling patterns, and architecture details, see Transaction State Machine.

The Steps

const API = "https://preprod.api.andamio.io/api/v2";
const headers = {
  "Content-Type": "application/json",
  "X-API-Key": APP_API_KEY,
  "Authorization": `Bearer ${userJwt}`,
};

// 1. Build — request unsigned CBOR from the API
const { unsigned_tx } = await fetch(`${API}/tx/course/student/assignment/commit`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    alias: "student1",
    course_id: "abc123...",
    slt_hash: "deadbeef...",
    assignment_info: "sha256:...",
    initiator_data: { usedAddresses: [...], changeAddress: "addr1..." },
  }),
}).then(r => r.json());

// 2. Sign — user approves in their wallet
const signedTx = await wallet.signTx(unsigned_tx);

// 3. Submit — send to Cardano
const txHash = await wallet.submitTx(signedTx);

// 4. Register — tell Andamio to track it
await fetch(`${API}/tx/register`, {
  method: "POST",
  headers,
  body: JSON.stringify({ tx_hash: txHash, tx_type: "assignment_submit" }),
});

// 5. Monitor — wait for DB sync via SSE
const events = new EventSource(`${API}/tx/stream/${txHash}`);
events.addEventListener("complete", (e) => {
  const { final_state } = JSON.parse(e.data);
  events.close();
  if (final_state === "updated") {
    // Success — safe to refetch data
  }
});

Wait for updated, not confirmed

confirmed means found on-chain, but the database hasn't synced yet. Wait for updated before refetching data.

TX Type Reference

When registering a transaction, use the correct tx_type:

Build EndpointTX TypeNotes
/tx/global/general/access-token/mintaccess_token_mint
/tx/instance/owner/course/createcourse_create
/tx/course/owner/teachers/manageteachers_update
/tx/course/teacher/modules/managemodules_manage
/tx/course/teacher/assignments/assessassessment_assess
/tx/course/student/assignment/commitassignment_submitFirst or update
/tx/course/student/assignment/updateassignment_submitSame as commit
/tx/course/student/credential/claimcredential_claim
/tx/instance/owner/project/createproject_create
/tx/project/owner/managers/managemanagers_manage
/tx/project/manager/tasks/managetasks_manage
/tx/project/manager/tasks/assesstask_assess
/tx/project/contributor/task/commitproject_joinJoin + commit
/tx/project/contributor/credential/claimproject_credential_claimRequires task_hash metadata

App Template Hooks

The andamio-app-template provides production-ready React hooks that handle the entire transaction lifecycle:

HookPurpose
useTransactionBuild, sign, submit, register — full lifecycle
useTxStreamSSE stream for real-time state updates

These hooks abstract the manual fetch/sign/submit code shown above. See the How Transactions Work README section for usage examples.

Next Steps