Managed Investments

One side provides the capital, the other provides the work. Profit is split by an agreed ratio. Loss falls on the capital.

The asymmetry is the point. The manager who loses the venture's money loses the work put into it and walks away owing nothing; the investor loses the money. Neither outcome is a penalty — it is the division of risk the two sides actually agreed to. The API enforces it: record_loss never touches the manager's side of the ledger, and the manager's profit share is not a fee that survives a bad year.

Base path: /api/v1/pfp/managed-investments · Religious reading: Mudaraba

Two mandates

`mandate_type`	The manager may
`restricted` (default)	Only invest within the declared field, and within `business_restrictions`
`unrestricted`	Invest at its own discretion

business_restrictions is a list of strings and is taken into account when the mandate is restricted. It is a record of the agreement, not an enforcement mechanism — the platform stores it and reports on it; it does not vet individual investments against it.

Statuses

draft ──submit──> under_review ──review──> review_passed
  │                    │                        │
  │                    └──reject──> rejected    │
  │                                             │
  └──────────────── fund ───────────────────────┘
                      │
                      v
                   funded ──activate──> active
                      │                    │
                      └────── complete ────┴──> completed
                                           │
                             loss wipes out │ current_value
                                           v
                                      liquidated

Status	Meaning
`draft`	Terms recorded
`under_review`	Submitted for approval
`review_passed`	A conclusion is attached
`rejected`	Terminal. Requires a `reason`
`funded`	Capital handed to the manager
`active`	The manager is running the venture; profit and loss can be recorded
`completed`	Settled at term
`liquidated`	The capital was wiped out

completed and liquidated are deliberately distinct. A venture that lost its capital is not the same event as one that ran its term and settled, and collapsing the two would make a failed contract indistinguishable from a successful one in any report built on status.

There is no liquidate endpoint: the platform sets liquidated itself, the moment a recorded loss drives current_value to zero. actual_end_date is set at the same time.

In the secular reading fund is reachable from draft as well as review_passed.

Create a contract

POST /api/v1/pfp/managed-investments

{
  "customer_id": "8f2a1c44-0b6e-4d51-9a3f-1c8e5b7d2a90",
  "region": "RU",
  "currency": "RUB",
  "capital_amount": "2000000000",
  "business_type": "Wholesale distribution of building materials",
  "business_description": "Regional distribution across Tatarstan and Mari El",
  "mandate_type": "restricted",
  "business_restrictions": ["No trade financing", "No FX positions"],
  "profit_sharing_ratio": { "bank": 30, "customer": 70 },
  "term_months": 24,
  "reporting_frequency": "quarterly"
}

Field	Type	Required	Notes
`customer_id`	uuid	✅	The manager
`region`	string	✅	Contract region
`currency`	string	✅	ISO 4217
`capital_amount`	string	✅	Minor units. Provided by the `bank` side
`business_type`	string	✅	The venture the manager will run
`profit_sharing_ratio`	object	✅	`{"bank": n, "customer": m}`, whole percent, must sum to 100
`term_months`	integer	✅	1–120
`mandate_type`	enum	—	`restricted` (default) \| `unrestricted`
`business_restrictions`	array	—	Strings
`business_description`	string	—	Free text
`reporting_frequency`	enum	—	`monthly` \| `quarterly` \| `semi_annually` \| `annually`
`metadata`	object	—	Returned untouched

Note the ratio in the example: the manager takes 70 % of profit while contributing no capital. That is normal for this product — the manager's contribution is the work, and it is priced in the profit share.

Lifecycle transitions

POST /api/v1/pfp/managed-investments/{id}/submit     # no body
POST /api/v1/pfp/managed-investments/{id}/review     # approved_by required
POST /api/v1/pfp/managed-investments/{id}/reject     # reason required
POST /api/v1/pfp/managed-investments/{id}/fund       # no body
POST /api/v1/pfp/managed-investments/{id}/activate   # no body

fund records that the capital has been handed over. activate records that the manager has started trading — profit and loss are accepted only from active.

Profit

POST /api/v1/pfp/managed-investments/{id}/profit

{
  "gross_profit": "180000000",
  "period_end_date": "2026-12-31"
}

Both fields are required. The gross profit is split by profit_sharing_ratio and the manager's share is moved to it by a ledger posting dated period_end_date. It is not an accrual on paper.

Each distribution appends to the history:

{
  "profit_distributions": [
    {
      "date": "2026-12-31",
      "gross_profit": "180000000",
      "bank_share": "54000000",
      "customer_share": "126000000"
    }
  ]
}

current_value — the investor's position — grows by the investor's share, not by the gross.

Zero is a legitimate report. A period that earned nothing still closes: send "0" and the reporting date advances. A negative gross profit is refused — a loss is a different transition with different arithmetic.

Loss

POST /api/v1/pfp/managed-investments/{id}/loss

{
  "amount": "40000000",
  "period_end_date": "2027-03-31"
}

The loss is applied to current_value — the capital at risk — and capped at it. You cannot lose more than was invested. A loss larger than the remaining value is recorded at the value that actually existed, and current_value goes to zero rather than negative.

The manager's side is untouched. There is no clawback of previously distributed profit shares and no debt created against the manager.

The history goes into metadata.losses — not into a field of its own, unlike profit_distributions:

{
  "metadata": {
    "losses": [
      { "date": "2027-03-31", "loss_amount": "40000000", "new_value": "1960000000" }
    ]
  }
}

Unlike profit, a loss of zero is refused: there is nothing to record.

A loss also advances the reporting date, exactly as a profit distribution does. A period closed at a loss is still a period reported.

Settle at term

POST /api/v1/pfp/managed-investments/{id}/complete

{ "final_value": "2200000000" }

Reachable from funded and active. Sets actual_end_date, writes current_value to final_value, and records the settlement in metadata.final_settlement:

{
  "final_settlement": {
    "returned_to_bank": "2014000000",
    "total_profit": "180000000",
    "total_loss": "40000000"
  }
}

returned_to_bank is capital_amount + bank_profit_share − total_loss — the capital back, plus the investor's accumulated profit share, less the losses borne.

List and read

GET /api/v1/pfp/managed-investments

Query parameter	Values
`status`	any status above
`region`	contract region
`type`	`restricted` \| `unrestricted`
`customer_id`	uuid
`env`	`test` \| `prod`

GET /api/v1/pfp/managed-investments/{id}

Managed Investments

Two mandates​

Statuses​

Create a contract​

Lifecycle transitions​

Profit​

Loss​

Settle at term​

List and read​