> For the complete documentation index, see [llms.txt](https://docs.t-rex.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.t-rex.network/guides/journeys/j3.-transfer-agent-journey-operations-on-a-live-asset.md).
# J3. Transfer agent journey: operations on a live asset
The transfer agent is the operator that keeps the register of an asset on the Issuer's behalf. In the protocol it is a set of roles: the Token Agent roles on the token, and the Registry Agent role on the eligibility registry. They are typically held by one operator, which is the Issuer itself or a provider it appoints. This journey starts when the Issuer grants the agent roles. It has no end: it lists the situations an agent meets in the life of the asset, and the operation that answers each. An agent holds no tokens and no key of any holder. It holds roles, each of which opens specific functions.
## Stages
The stages are situations, not a sequence. Stage 1 comes first. The others occur in any order.
| # | Stage | Flow | Who acts | Outcome |
| - | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 1 | Receive the agent roles | [25 Commission a suite and grant roles](/guides/issuer/25.-commission-a-suite-and-grant-roles.md) | Issuer | The operator holds the roles of the operations it performs, in the Issuer's domain |
| 2 | A subscription is settled | [08 Mint a position to an investor](/guides/positions/08.-mint-a-position-to-an-investor.md) | Token Agent (`AGENT_MINTER`) | New units exist, credited to an eligible investor |
| 3 | A redemption is settled | [09 Burn a position](/guides/positions/09.-burn-a-position.md) | Token Agent (`AGENT_BURNER`) | Units are destroyed |
| 4 | A holder's address cannot link itself | [06 Register an investor for an asset](/guides/agents/06.-register-an-investor-for-an-asset.md) | Registry Agent (`AGENT`) | The address resolves to the holder's identity for this asset |
| 5 | A registration has to change | [17 Update an investor's registration](/guides/agents/17.-update-an-investors-registration.md), [18 Remove an investor's registration](/guides/agents/18.-remove-an-investors-registration.md) | Registry Agent (`AGENT`) | The local record is corrected or deleted |
| 6 | Tokens have to be immobilized | [13 Freeze and unfreeze an address or a partial balance](/guides/agents/13.-freeze-and-unfreeze-an-address-or-a-partial-balance.md) | Token Agent (`AGENT_ADDRESS_FREEZER`, `AGENT_PARTIAL_FREEZER`) | An address, or an amount on it, cannot move |
| 7 | A decision overrides the holder | [14 Execute a forced transfer](/guides/agents/14.-execute-a-forced-transfer.md) | Token Agent (`AGENT_FORCED_TRANSFER`) | Tokens move to an eligible recipient without the holder |
| 8 | A holder lost a wallet | [15 Recover a position from a lost wallet](/guides/agents/15.-recover-a-position-from-a-lost-wallet.md) | Token Agent (`AGENT_RECOVERY_ADDRESS`) | The whole balance is at a new address of the same identity |
| 9 | An incident requires a halt | [16 Pause and unpause a token](/guides/agents/16.-pause-and-unpause-a-token.md) | Token Agent (`AGENT_PAUSER`) | Movements between holders stop, then resume |
## Overview
```mermaid
flowchart LR
R["1. Roles granted
25"] --> L(("Live asset"))
L -.-> M["2. Mint
08"]
L -.-> B["3. Burn
09"]
L -.-> G["4, 5. Registrations
06, 17, 18"]
L -.-> F["6. Freeze
13"]
L -.-> T["7. Forced transfer
14"]
L -.-> W["8. Wallet recovery
15"]
L -.-> P["9. Pause
16"]
```
## What the persona sees and does
**1. Receive the agent roles.** The Issuer grants the operator the roles of the operations it performs, in the domain of the asset. The roles are separate: an operator that mints does not have to be able to freeze or to force a transfer. The operator checks what it holds with `hasRole` on the access manager, with the role identifier of the asset's domain. A role granted with an execution delay means each call is scheduled first and executed after the delay.
**2. A subscription is settled.** The Issuer confirms, under its own process, that an investor has paid for a subscription. The agent checks that the investor is eligible and that the rules of the asset allow the amount, then mints. The token applies the same two gates itself: a mint to an investor that is not eligible reverts. The agent decides that the mint happens. The token decides whether it is allowed.
**3. A redemption is settled.** The Issuer confirms a redemption, a buy-back or a cancellation. The agent burns the units at the holder's address. A burn needs no signature from the holder and passes no gate, since nothing is received. It releases frozen tokens when the free balance is not enough.
**4. A holder's address cannot link itself.** Most holders need nothing from the agent: an ONCHAINID, or a wallet its owner linked, is recognized by every asset. The agent registers an address only when it cannot link itself and has to hold the asset: a custody account, a contract that cannot sign, an omnibus wallet, recorded under the entity that operates it. The registration is local to the asset. The agent keeps the evidence that the address belongs to the identity, because the contract takes its word.
**5. A registration has to change.** A local registration made under the wrong identity is corrected. A registration that is no longer needed is deleted, and the address falls back to its global link if it has one. An update changes who the tokens at that address are attributed to, without any transfer. A removal does so only when the address is linked globally to another identity. The agent treats both as carefully as a movement.
**6. Tokens have to be immobilized.** An investigation, a lock-up, a pledge, a compromised wallet. The agent freezes an address entirely, so that it neither sends nor receives, or freezes an amount on it. The tokens stay owned by their holder. The agent unfreezes when the cause is gone.
**7. A decision overrides the holder.** A court order, a succession, the correction of an error. The agent moves the tokens itself. A forced transfer goes through freezes and does not ask the compliance rules. It keeps one gate: the recipient must be eligible. The agent records the decision that justifies it, since the contract executes whatever the role allows.
**8. A holder lost a wallet.** A holder that still controls its ONCHAINID moves its free tokens itself, through its identity. The agent acts when the holder cannot, or when the lost wallet holds frozen tokens. It moves the whole balance, with its freezes, to another address of the same identity. The holder's identity, claims and eligibility are untouched.
**9. An incident requires a halt.** The agent pauses the token. Transfers between holders revert until it lifts the pause. Mints and burns still work during a pause. Forced transfers and recoveries do not: to run one, the agent lifts the pause, acts, and pauses again if needed. The token can also pause itself when the cross-chain layer delivers a settlement the register cannot account for: the response is in [36](/guides/cross-chain/36.-handle-a-late-reconciliation-or-a-halt.md).
## Where journeys diverge
* **The position is active on a satellite.** An agent cannot freeze, burn or force a transfer on a satellite. It recalls the position to the reference chain first: [32](/guides/cross-chain/32.-recall-a-position-to-the-reference-chain.md).
* **A holder must leave the asset.** The operations of stages 6, 7 and 3 are chained in a set order: [J5](/guides/journeys/j5.-offboarding-journey-an-investor-that-must-no-longer-hold-or-receive.md).
* **A holder lost the keys of its identity, not a wallet.** The agent has no authority over an identity. The holder's guardians recover it: [21](/guides/identity/21.-recover-access-to-an-onchainid.md). If that is not possible, the agent moves the positions of its asset to a new identity with stage 7.
* **A holder became ineligible.** Nothing happens to its position. It keeps it, can still send to an eligible recipient and cannot receive. The Issuer decides whether to freeze: stage 6.
* **A validation is stuck.** The release of reservations is the Validation Keeper's work, not the agent's: [35](/guides/cross-chain/35.-discard-or-resolve-a-validation.md).
## Related journeys
* [J1 Issuer journey: launch an asset](/guides/journeys/j1.-issuer-journey-launch-an-asset.md) : how the asset came to be live
* [J5 Offboarding journey: an investor that must no longer hold or receive](/guides/journeys/j5.-offboarding-journey-an-investor-that-must-no-longer-hold-or-receive.md) : the agent operations chained for an exclusion
* [J4 Cross-chain journey: distribute and reconcile](/guides/journeys/j4.-cross-chain-journey-distribute-and-reconcile.md) : the same asset on satellites
---
# 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.t-rex.network/guides/journeys/j3.-transfer-agent-journey-operations-on-a-live-asset.md?ask=&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.