> 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/create-and-manage-instructions.md).

# Create & Manage Instructions

Instructions are the **starting point for executing financial operations** within the ledger. They act as **containers** that hold multiple **activities**, such as **fund transfers** or **account updates**.

An **instruction itself does not move funds**—it simply defines the operations that need to be executed. Once an instruction is processed, it generates **movements**, which update **wallet balances**.

### **How Instructions Work**

1. **Add activities to an instruction:** Define fund transfers, allocations, or other operations.
2. **Write the instruction:** Once all activities are added, submit the instruction for processing.
3. **Instruction is processed:** The system generates **movements** based on activities.
4. **Movements update wallet balances:** Once finalized, the transaction is complete.

***

### **Creating Instructions Using the CLI**

#### **Step 1: Add Activities to an Instruction**

Each activity within an instruction defines a specific action (e.g., debiting and crediting wallets). Multiple activities can be added before finalizing an instruction.

**Example CLI Command**

```sh
./luca add-activity - /chart/company/revenue/default/USD \
/group/customers/customer123/default/USD 100
./luca add-activity - /chart/company/revenue/default/USD \
/chart/company/fees/default/USD 5
```

* **/chart/company/revenue/default/USD** → Source wallet (Revenue Account).
* **/group/customers/customer123/default/USD** → Customer’s wallet.
* **100** → Amount being transferred.
* **Second activity:** Transfers **$5** as a **fee deduction**.

> **Note:** You can add **multiple activities** before finalizing an instruction. This ensures that all related transactions (e.g., main payment + fees) are processed **together**.

#### **Step 2: Write the Instruction**

Once all activities are added, execute:

```sh
./luca write-instruction
```

* This **submits the instruction to the ledger**.
* **Movements are not created yet**—they will be generated once the instruction is processed.

***

### **Creating Instructions Using the API**

For system integrations, instructions can be **created programmatically** via API.

#### **API Endpoint**

```http
POST /api/v1/instruction/
```

#### **Updated API Payload Example**

```json
{
  "id": "instruction-123",
  "activities": [
    {
      "debit_wallet_address": "/chart/company/revenue/default/USD",
      "credit_wallet_address": "/group/customers/customer123/default/USD",
      "amount": 100,
      "decimal_places": 2,
      "attributes": {
        "transaction-id": "9d8eb5af-b758-4237-9da6-435c2555790e"
      }
    },
    {
      "debit_wallet_address": "/chart/company/revenue/default/USD",
      "credit_wallet_address": "/chart/company/fees/default/USD",
      "amount": 5,
      "decimal_places": 2
    }
  ],
  "state": "ACTIVE"
}
```

#### **Key Parameters**

* **id** → Unique instruction identifier.
* **debit\_wallet\_address** → The **source wallet** for the transaction.
* **credit\_wallet\_address** → The **destination wallet**.
* **amount** → Value to transfer.
* **decimal\_places** → Number of decimal places for precision.
* **attributes** → Metadata for tracking (`transaction-id`).
* **state** → The current instruction state (`PASSIVE`, `ACTIVE`).

***

### **Finalizing Instructions and Generating Movements**

#### **CLI Finalization**

If activities were added without `--finalize`, finalize them manually after writing the instruction:

```sh
./luca finalize-instruction instruction-123
```

This **triggers movement creation** based on the activities.

#### **Finalizing an Instruction via API**

If `"state": "ACTIVE"`, finalize it by calling:

```http
POST /api/v1/instruction/finalize
```

```json
{
  "instruction_id": "instruction-123"
}
```

This ensures **all included activities are processed together**.

#### **Retrieving the Generated Movements**

Once finalized, movements can be retrieved using:

```http
GET /api/v1/movement?instruction_id=instruction-123
```

This confirms **which movements were created from the instruction**.

***

### **Best Practices for Managing Instructions**

#### **1. Validate Chart and Wallet Structure**

Ensure that all **wallet paths** are correctly mapped to avoid processing errors.

#### **2. Use Finalization Carefully**

The `--finalize` flag (CLI) or `finalize` parameter (API) locks the activity, preventing further edits.

#### **3. Audit Instructions Regularly**

Periodically review instructions to **ensure business rules and ledger integrity**.

***

### **Example Use Cases**

#### **1. Processing Customer Payments**

* **Scenario:** A customer makes a **$100** payment.
* **Example:** The instruction contains one activity to debit the customer’s wallet and credit the company’s revenue account.

#### **2. Handling Multi-Step Transactions**

* **Scenario:** A payment includes a **service fee**.
* **Example:**
  * Activity 1: **$100** to the company’s revenue wallet.
  * Activity 2: **$5** deducted as a service fee.

#### **3. Automating Fund Transfers via API**

* **Scenario:** Automating internal fund allocations.
* **Example:** Move funds from a **revenue wallet** to an **expense wallet** on a scheduled basis.

***

### **Key Takeaways**

* Instructions act as containers for multiple activities.
* Activities define individual operations (debiting and crediting wallets).
* Writing an instruction does not update balances—it queues activities for processing.
* Movements are generated from instructions after processing.
* Finalizing an instruction creates movements that update wallet balances.

####


---

# 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/create-and-manage-instructions.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.