> For the complete documentation index, see [llms.txt](https://docs.pokefi.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pokefi.xyz/core-concepts/loan-lifecycle.md). # How a Loan Works Every PokeFi loan moves through a defined sequence of states. Understanding these states clarifies what is possible at each point for both borrowers and lenders. A loan is a term loan: its amount, interest, and maturity are fixed when it is funded, and it settles either by repayment or by default at maturity. *** ## Lifecycle at a Glance ``` BORROWER PokeFi (Solana + vault) LENDER -------- ----------------------- ------ Vault card ---------------> Card authenticated, insured, minted as an on-chain title token Request loan -------------> Loan request published on-chain (amount, term, max APR) (collateral, valuation, terms) <----- Reviews and funds (locks USDC) Title token -> escrow (PDA) · USDC released to borrower <--------- -- loan runs -- Repay principal + interest -> Escrow releases title token USDC + interest --> Lender back to borrower -- OR default at maturity -- (no repayment) -> Title token transfers to lender / card to liquidation Proceeds settle the loan Collateral or USDC --> Lender ``` *** ## Loan States | State | Description | | ----------- | ------------------------------------------------------------------------------- | | `open` | Request published by the borrower; awaiting a lender | | `funded` | A lender funded the request; USDC is with the borrower and the card is escrowed | | `repaid` | Principal plus interest fully repaid; card released to the borrower | | `defaulted` | Maturity passed without full repayment; card transferred to the lender | | `cancelled` | Borrower cancelled an unfunded request; card released from escrow | *** ## State Transitions ``` open ├── funded │ ├── repaid (borrower repays principal + interest before maturity) │ └── defaulted (maturity passes without full repayment) └── cancelled (borrower cancels an unfunded request) ``` Only an `open` loan can be cancelled or funded. Only a `funded` loan can be repaid or defaulted. These transitions are enforced by program logic and by the database RPCs that back the application. *** ## Open The borrower publishes a request against a vaulted card. At this point: * The loan request is recorded on-chain and in the public explorer with the collateral, valuation, and requested terms. * The card's title token moves into the loan escrow, a program-derived address the borrower no longer controls. * The card's status becomes `escrowed`, so it cannot back a second loan at the same time. * The borrower sets the principal, the term, and the maximum APR they will accept. A card can only back **one live loan at a time**. While a request is open or funded, that card is locked to it. The borrower can **cancel** an open request at any time before it is funded, which releases the title token from escrow and returns the card to `vaulted` status. *** ## Funded A lender funds the request at an APR at or below the borrower's stated maximum. Funding is atomic and locks the loan's economics for its full life: * The lender's USDC is released to the borrower. * The **agreed APR** is recorded, along with the resulting **loan-to-value** computed against the card's Reference Price. * The **total repayment** (principal plus fixed interest) is calculated once and stored. Interest is `principal × APR × term ÷ 365`. * The **start** and **maturity** timestamps are set. Maturity is the start plus the term in days. From this point there are no margin calls, no rate changes, and no mid-loan liquidations. The card stays in escrow until the loan settles. *** ## Repaid The borrower repays in USDC before maturity. Repayment can be made in one payment or in parts: * Each repayment is recorded, and the outstanding balance decreases. * When cumulative repayments reach the total repayment amount, the loan is marked `repaid`. * The title token is released from escrow back to the borrower, and the card returns to `vaulted` status. The borrower now holds full title again and can redeem the physical card, keep it vaulted, or use it as collateral for a future loan. *** ## Defaulted Maturity passes without full repayment. Any time after maturity, the default can be claimed: * The loan is marked `defaulted`. * The card's title token transfers to the lender, who becomes the card's owner of record. * The lender can redeem the physical card or route it to the liquidation channel to recover USDC. Default is deterministic. It is defined entirely by maturity elapsing without full repayment, and the collateral transfer follows automatically. The borrower keeps the USDC they borrowed; the lender keeps the card. {% hint style="info" %} A default can only be claimed **after** maturity. Before maturity, a funded loan cannot be defaulted no matter how the card's market price moves. This protects borrowers from losing a card over short-term volatility. {% endhint %} *** ## Cancelled A borrower can cancel a loan request while it is still `open` (unfunded). Cancellation: * Releases the title token from escrow and returns the card to `vaulted` status. * Records a `cancelled` event in the public ledger. Once a loan is funded, it can no longer be cancelled. It must settle by repayment or default. *** ## Fixed at Origination When a loan is funded, the following are locked and cannot change for the life of the loan: * Principal * APR and the resulting total repayment amount * Term and maturity date * Collateral (the specific card backing the loan) This is the defining property of a term loan. Both sides know the exact economics up front, and neither the market nor the counterparty can alter them mid-loan. *** ## Every Transition Is Public Each state change emits an event to an append-only ledger: `requested`, `funded`, `repayment`, `repaid`, `defaulted`, `claimed`, `cancelled`. These events power the public transparency explorer, where anyone can audit the full history of any loan and its collateral. See [Architecture Overview](/technical-reference/architecture.md) for how the ledger is built. --- # 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.pokefi.xyz/core-concepts/loan-lifecycle.md?ask=&goal= ``` `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.