> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-ledger/integrate-with-xyb-ledger/set-up-transaction-workflows/managing-movements-in-the-ledger.md).

# Managing Movements in the Ledger

Movements are the fundamental units of financial operations in the ledger, representing the transfer of funds between wallets. They track value flow between debit and credit wallets, ensuring accurate financial records and transaction integrity.

#### States of a Movement

Movements transition through distinct states during their lifecycle:

* **PASSIVE**: The movement is created but does not yet have an assigned amount. It serves as a placeholder.
* **ACTIVE**: An amount has been assigned, but the movement has not been finalized. Funds are reserved but not committed.
* **COMPLETE**: The movement is finalized, and balances are updated accordingly. This state is irreversible.
* **CANCELLED**: The movement is voided without affecting balances. This is used for invalid or erroneous transactions.

#### Executing Movements

Executing a movement involves defining the transaction details and transitioning through the lifecycle.

**Step 1: Create a Movement**

Define the movement by specifying the source and destination wallets, the amount, and other parameters. Use the following command:

```sh
luca add-activity - /chart/company/expenses/default/USD /chart/company/revenue/default/USD 50 --finalize
```

* `/chart/company/expenses/default/USD`: Source wallet (debit).
* `/chart/company/revenue/default/USD`: Destination wallet (credit).
* `50`: Amount being transferred.
* `--finalize`: Directly finalizes the movement, transitioning it to **COMPLETE**.

**Step 2: Finalize the Movement**

Movements created without the `--finalize` flag remain in an **ACTIVE** state and must be explicitly finalized using:

```sh
luca write-instruction
```

This command commits the movement, updating the relevant wallet balances.

#### API-Based Movements

Movements can also be managed programmatically via the API.

**API Endpoint**

```
POST /api/v1/movement/
```

**Payload Example**

```json
{
  "id": "548133b4-8067-44f6-ba67-e864c089bb8d",
  "debit_wallet_address": "/chart/primary/nostro/default/GBP",
  "credit_wallet_address": "/group/eu/customer7331/default/GBP",
  "amount": 150,
  "decimal_places": 2,
  "attributes": {
    "payment-id": "9d8eb5af-b758-4237-9da6-435c2555790e"
  },
  "state": "ACTIVE",
  "value_date": "2022-10-13T09:30:55.000893Z"
}
```

* `debit_wallet_address`: Source wallet.
* `credit_wallet_address`: Destination wallet.
* `amount`: Transfer amount.
* `decimal_places`: Precision for the transaction.
* `state`: Current state (e.g., **ACTIVE** or **PASSIVE**).
* `value_date`: The date when the transaction takes effect.

A separate API call is required to finalize the movement.

#### Best Practices for Managing Movements

* **Track Movement States**: Regularly monitor movement states to ensure transactions progress as expected. Movements stuck in **PASSIVE** or **ACTIVE** states should be reviewed.
* **Cancel Unneeded Movements**: If a movement is no longer required, cancel it to prevent unnecessary ledger entries.
* **Use Finalization Wisely**: Directly finalizing a movement (`--finalize`) is efficient but should only be used when all details are confirmed.

#### Example Use Cases

1. **Expense Tracking**: Debit an expense account and credit a revenue account to record operational costs.
2. **Revenue Allocation**: Move funds from a revenue wallet to a designated expense or salary wallet.
3. **Multi-Activity Transactions**: Multiple activities (e.g., salary payment and fee deduction) can be grouped into a single instruction before execution.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xyb.co/xyb-ledger/integrate-with-xyb-ledger/set-up-transaction-workflows/managing-movements-in-the-ledger.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.