Documentation Index
Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Understanding resource state transitions is essential for building robust integrations. This guide documents the lifecycle of key resources in the Dakota API.
Application Lifecycle
Applications go through a defined lifecycle from creation to decision. Understanding these states helps you build proper status handling and user feedback.
Application-Level States
| Status | Description | Allowed Actions |
|---|
pending | Draft state. Application created but not yet submitted. | Add/edit entities, upload documents, submit |
submitted | Application submitted for review. | View only |
completed | Review complete. Check application_decision for result. | View only |
Application Decisions
Once an application reaches completed status, the application_decision field contains the outcome:
| Decision | Description |
|---|
approved | Application approved. Customer can transact. |
declined | Application declined. See compliance notes for details. |
withdrawn | Application was withdrawn before a decision was made. |
Applicant-Level States (Business & Individuals)
Within an application, each entity (business or individual) has its own status:
| Status | Description |
|---|
pending | Entity data incomplete or not yet submitted |
submitted | Entity submitted for review |
completed | Review complete for this entity |
Transaction Lifecycle
Transactions progress through multiple states from initiation to completion.
Transaction States
Transaction Status Reference
| Status | Terminal | Description |
|---|
not_started | No | Transaction created but processing not begun |
pending | No | Transaction is queued for processing |
processing | No | Transaction is actively being processed |
in_progress | No | Transaction is being processed |
awaiting_confirmation | No | Waiting for blockchain confirmation |
broadcasted | No | Submitted to blockchain, awaiting confirmation |
completed | Yes | Transaction completed successfully |
invalid | Yes | Transaction parameters were invalid |
failed | Yes | Transaction failed during processing |
canceled | Yes | Transaction was canceled |
reversed | Yes | Transaction was reversed after completion |
rejected | Yes | Transaction was rejected by compliance or provider |
timed_out | Yes | Transaction timed out |
Terminal vs Non-Terminal States
Terminal states indicate the transaction has reached a final outcome and will not change:
completed, invalid, failed, canceled, reversed, rejected, timed_out
Non-terminal states indicate the transaction is still in progress:
not_started, pending, processing, in_progress, awaiting_confirmation, broadcasted
Auto Transaction Lifecycle
Auto transactions have their own lifecycle:
| Status | Terminal | Description |
|---|
pending | No | Scheduled but not yet processed |
processing | No | Currently being executed |
completed | Yes | Successfully completed |
failed | Yes | Failed during processing |
canceled | Yes | Canceled before processing |
reversed | Yes | Reversed after completion |
Handling State Changes
Polling for Status Updates
For non-terminal states, poll periodically to check for updates:
async function waitForCompletion(transactionId, maxAttempts = 30) {
const terminalStates = ['completed', 'failed', 'canceled', 'reversed', 'rejected', 'invalid', 'timed_out'];
for (let i = 0; i < maxAttempts; i++) {
const response = await fetch(`https://api.platform.dakota.xyz/auto-transactions/${transactionId}`, {
headers: { 'x-api-key': API_KEY }
});
const transaction = await response.json();
if (terminalStates.includes(transaction.status)) {
return transaction;
}
// Wait before next poll (exponential backoff)
await new Promise(r => setTimeout(r, Math.min(1000 * Math.pow(2, i), 30000)));
}
throw new Error('Transaction did not complete within expected time');
}
Using Webhooks for State Changes
Instead of polling, configure webhooks to receive real-time notifications:
// Webhook handler for transaction status changes
app.post('/webhooks/dakota', (req, res) => {
const event = req.body;
if (event.type === 'transaction.status_changed') {
const { transaction_id, old_status, new_status } = event.data;
console.log(`Transaction ${transaction_id}: ${old_status} → ${new_status}`);
// Handle terminal states
if (['completed', 'failed', 'canceled'].includes(new_status)) {
// Update your database, notify user, etc.
}
}
res.status(200).send('OK');
});
State Transition Rules
Valid Transitions
Not all state transitions are valid. The API enforces these rules:
Applications:
pending → submitted (via submit endpoint)submitted → completed (automatic after review)
Transactions:
- Cannot transition from terminal states
canceled can only be triggered while in non-terminal statereversed can only occur after completed
Error Handling
See Error Codes for all error types and handling best practices.
