[Beta] Collateral

Overview

The Collateral API lets you, as a lender, take accounts that your borrowers hold at Pave Bank as security, and reserve, release or take ownership of the pledged units. Both you and your borrower are Pave Bank legal entities. This section is written from the lender's point of view, and every call uses an access token scoped to your legal entity. Read endpoints work with a viewer or admin credential, write endpoints need admin, and a write against a pledge you are not the lender on returns permission_denied.

Borrowers can use the same API to monitor their position. With a token scoped to the borrower's legal entity, List Agreements, Get Agreement, List Pledges, Get Pledge and List Holds return the agreements, pledges and holds where that entity is the borrower. The write endpoints (approve, reject, lock, release, enforce and cancel) are lender only. Borrowers pledge accounts through the Pave Bank app, not through this API.

Each endpoint page shows a party badge next to the role badge. In summary:

There are three objects:

• Agreement. A collateral agreement between you and one borrower. Agreements are set up by Pave Bank and carry the agreed dispute_window_hours used by enforcement. Pledges are always created under an agreement.
• Pledge. A borrower account placed under an agreement. You can only lock against approved pledges. Each pledge reports total_units, locked_units and available_units for the pledged account. An account can have at most one active pledge per agreement.
• Hold. Your reservation of units on an approved pledge. Locked units stay in the borrower's account but are removed from the borrower's spendable balance. A hold is a snapshot of your position on the pledge, not a record you update. Each lock, release or enforcement action closes the current hold and returns a new one with its own ID. Use the hold from your latest call, or List Holds filtered by pledge_id, to read your current position.

Step 1: A Pledge Arrives

Your borrower pledges one or more of their accounts under the agreement in the Pave Bank app. Each pledge appears to you as pending. Watch for them with List Pledges filtered by status=pending, and inspect one with Get Pledge.

Pave Bank can also set up pledges on the borrower's behalf. Those pledges may be created directly as approved, in which case Step 2 does not apply and you can lock against them immediately.

Step 2: Approve or Reject

A pending pledge needs one approval before you can use it. Either of the following moves it to approved:

• You call Approve Pledge, optionally setting your own external_id on the agreement.
• Pave Bank approves it during onboarding or at your request.

You can instead call Reject Pledge. A rejected pledge is final. The borrower must pledge the account again if needed.

Step 3: Lock Units

Reserve units with Lock Pledge Units. The hold is locked and the pledge's available_units decreases by the same amount. You can lock additional units on the same pledge later; the combined total is returned as a new hold with a new ID.

Step 4: Release Units

When the borrower's obligation is met, return units with Release Pledge Units. Releasing everything marks the hold released. A partial release returns a smaller locked hold with a new ID.

Step 5: Enforce on Default

If the borrower defaults, call Start Enforcement with the units to enforce. It returns the enforcement hold in dispute_window status with its dispute_deadline, which is the agreement's dispute_window_hours after the call, and the borrower is notified. When the deadline passes, the units are transferred to your account and the hold becomes enforced. Enforcing only part of the locked units leaves a separate locked hold for the remainder, so the pledge shows two holds during the window.

You can cancel before the deadline with Cancel Enforcement, which merges everything back into a single locked hold and returns an empty body. Read the new hold with List Holds.

Removing a Pledge

Pave Bank can remove a pledge at your request or the borrower's. Removal is only possible when the pledge has no locked or dispute_window hold, so release any held units first. A removed pledge frees the account to be pledged again under the same agreement.

Statuses

Agreement

Pledge

Hold

Units

Unit fields (units, total_units, locked_units, available_units) are amounts of the pledged instrument, identified by the pledge's instrument_type. Like every other amount in the API they are expressed in minor units as decimal strings. See Currencies for the convention.

Instrument assets such as TBILL, MMF and BONDS have 6 decimals, so one whole unit is "1000000" and 2,500 units is "2500000000".