> 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-platform-1/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.