> ## Documentation Index
> Fetch the complete documentation index at: https://docs.busha.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Busha Pledges
> Let a customer lock their own Busha assets as collateral for a credit agreement with your business, without ever taking custody of those assets yourself.
## What are Pledges?
Pledges let a Busha customer lock a portion of their own crypto balance as collateral for a credit agreement with your business: a loan, a line of credit, or any arrangement where you need security against funds you don't hold.
The customer's assets stay in their own Busha account. They're never transferred to you. Busha locks them in place for the duration of the agreement, releases them as the customer repays, and if the customer defaults, lets you request liquidation under a notice period defined by the pledge mandate.
Three parties are involved in every pledge:
* **The customer** owns the assets and must authorize the pledge themselves via OAuth2
* **The beneficiary** is your business, the counterparty benefiting from the collateral
* **Busha** is the custodian enforcing the lock and mediating the lifecycle
Pledges require [Busha OAuth2](/guides/oauth/introduction). Unlike most
Business API resources, a pledge cannot be created with a business Secret Key
alone. Busha needs cryptographic proof that the customer consented to the
specific assets being locked.
## Why OAuth2, not a Secret Key
Every other resource in the Business API, quotes, transfers, customer management, either belongs to your business directly, or to a customer you created and administer via `X-BU-PROFILE-ID`. Pledges are different: the assets belong to an independent Busha user with their own login, outside your administration.
To lock those assets, your app must obtain an access token through the OAuth2 authorization code flow, with the customer completing login and consent on Busha's own hosted screen. Calling a pledge endpoint with a business Secret Key instead of a customer scoped OAuth2 token returns a `request_validation` error.
## Before you begin
Pledges sit on top of OAuth2, so make sure you have:
* A **Busha business account** with completed KYB (Know Your Business) verification.
* An **OAuth2 app** registered under your business account. See [Get access](/guides/oauth/get-access).
* The **pledge scopes** your integration needs, requested at OAuth2 app registration. See [Scopes](/guides/oauth/scopes#pledges).
* A **pledge configuration** enabled for your business account. This is set up on Busha's side, contact your integration manager if `pledges/quotes` returns `Pledge config not found`.
## The pledge scopes
| Scope | What it grants |
| ------------------- | ----------------------------------------------------------------------------------- |
| `pledges:read` | View pledge records, item status, and lifecycle events. |
| `pledges:write` | Create pledge quotes, lock approved assets, activate pledges, add or release items. |
| `pledges:liquidate` | Request or cancel liquidation of pledged assets. |
## The pledge lifecycle
A pledge moves through the following states over its lifetime:
| Status | Meaning |
| --------------------- | -------------------------------------------------------------------------- |
| `authorized` | Collateral locked. The credit agreement has not yet been confirmed active. |
| `active` | Beneficiary confirmed disbursement, the agreement is live. |
| `liquidation_pending` | A liquidation has been requested and is inside its notice period. |
| `released` | All pledged assets have been returned to the customer. |
| `liquidated` | Pledged assets were seized following a completed liquidation. |
| `expired` | The pledge lapsed before being activated. |
| `cancelled` | The pledge was called off before going active. |
A pledge quote and the pledge it creates both carry a short `expires_at`
window. If you don't call [Activate
pledge](/api-reference/pledges/create-pledge-quote#activate-pledge) before that window closes,
the pledge becomes unusable. Build your disbursement flow to activate
immediately after creating the pledge, not after external processing.
Each individual pledged item (one per asset in a multi asset pledge) tracks its own finer grained status as it's released or liquidated:
| Item status | Meaning |
| ---------------------- | --------------------------------------- |
| `locked` | Fully locked, untouched. |
| `partially_released` | Some has been returned to the customer. |
| `released` | Fully returned. |
| `partially_liquidated` | Some has been seized. |
| `liquidated` | Fully seized. |
## A typical integration
A lending product built on Pledges follows roughly this shape:
1. Your customer requests credit, offering their Busha crypto as collateral.
2. They authorize your app via OAuth2, consenting to the pledge scopes you requested.
3. You create a [pledge quote](/guides/pledges/quick-start#1-create-a-pledge-quote) to confirm the assets can be locked.
4. You [create the pledge](/guides/pledges/quick-start#2-create-the-pledge) from that quote and immediately [activate it](/guides/pledges/quick-start#3-activate-the-pledge) once you've disbursed funds.
5. As the customer repays, you [release](/api-reference/pledges/create-pledge-quote#release-pledge-items) collateral back to them, partially or in full.
6. If the customer defaults, you [request liquidation](/api-reference/pledges/create-pledge-quote#request-pledge-liquidation), which executes automatically after a notice period unless you [cancel it](/api-reference/pledges/create-pledge-quote#cancel-pledge-liquidation).
## Next steps
Walk through a full pledge lifecycle end to end, from quote to liquidation.
Full reference for every pledge endpoint, parameters, responses, and
required scopes.
Review the pledge scopes alongside the rest of the OAuth2 scope catalog.