> ## Documentation Index
> Fetch the complete documentation index at: https://developers.investorlift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust and limits

> The four trust tiers and their daily caps, the seller caps, the per-deal ceilings, the hold queue, the seller controls and the gateway limits.

<Note>
  The Marketplace API is in a private beta. It answers only for accounts Investorlift has enabled. [Access](/marketplace/access) says how to ask for one. A route shape on these pages can change before the beta ends. The changelog records every change.
</Note>

<Note>
  The figures on this page are the beta's. Investorlift measures what honest sellers and buyers do during the beta, and a
  figure can move before the beta ends. `GET /me` prints the caps that apply to your token today.
</Note>

Every buyer-side read and write runs under a trust tier. The tier comes from facts Investorlift already holds about the
person, never from the token or the client. Every daily cap counts per UTC day and resets at midnight UTC. Investorlift
can also stop a client, a user, an organization or a route: a stopped caller answers `403 forbidden` on its next
request. A cap you reach is not a reason for a stop.

## The four tiers

The tiers are cumulative. A tier holds only when every tier under it holds, so an accepted offer never lifts an account
with no verified phone.

| Tier | The facts                                                                                |
| ---- | ---------------------------------------------------------------------------------------- |
| `T0` | The email address is verified. Every account passed this.                                |
| `T1` | `T0`, the phone number is verified, and the account has the buyer designation.           |
| `T2` | `T1`, identity is verified, and a proof of funds document on file is inside its 90 days. |
| `T3` | `T2`, and one offer of this buyer was accepted on Mogul.                                 |

Full search access is a separate fact. A buyer with no attached or verified legal entity reads the first 50 deals only,
the same preview Mogul shows. `GET /me` names the step in `trust.next_step`, and prints each fact with its source in
`trust.facts`.

## The caps per tier

| Tier | Deal budget a day | Previews a day | Offers a day | Active chains | Inquiries a day | Address requests a day | Sellers a day |
| ---- | ----------------- | -------------- | ------------ | ------------- | --------------- | ---------------------- | ------------- |
| `T0` | 50                | 0              | 0            | 0             | 0               | 0                      | 5             |
| `T1` | 150               | 9              | 3            | 5             | 10              | 3                      | 25            |
| `T2` | 400               | 45             | 15           | 20            | 30              | 10                     | 50            |
| `T3` | 800               | 150            | 50           | 50            | 50              | 20                     | 100           |

The deal budget counts the deals the token gets, and one deal counts once a day. A list row counts the deal. So does a
single read, a preview, and a `deal.matched` delivery on a webhook or the feed. Active chains is a live count of the
offer chains open at one time, not a daily count. Sellers a day counts `GET /buy/sellers/{seller_id}`. When Mogul's identity gate for offers is on, a
`T1` offer answers `403 idv_required`, and `verification_url` carries the verification link.

## The seller caps

| Cap                                               | Figure |
| ------------------------------------------------- | ------ |
| Drafts one organization creates a day             | 50     |
| Contact-bearing rows a personal client gets a day | 500    |
| Contact-bearing rows a registered app gets a day  | 5,000  |

A contact-bearing row carries `email` or `phone` under `contacts:read`. A contact-bearing list reaches back to the
later of your connection date and 90 days. Rows with an active offer, or with an inquiry inside 30 days, are the
exception.

## Per-deal ceilings

Whoever writes, one deal takes 20 offers an hour, and 40 inquiries and address requests an hour together. Above a
ceiling, a buyer's new offer, counter, inquiry or address request goes to the hold queue, and Investorlift tells the
seller. An offer the seller logs above the ceiling answers `429 cap_reached` with `Retry-After: 3600`.

## Cold start and linked accounts

An account or a client under 14 days old, or under 20 writes, is new. The API samples its first five writes into the
hold queue and scores it against the population of its tier. For the caps, the API counts accounts as one actor when,
in one day, they share one of these:

* a phone hash
* a Plaid identity
* a payment instrument
* a device
* an egress address

A VoIP phone number stays at `T0` for API writes.

## The hold queue

A held write is not a refusal. Four operations can answer `202` for a held write:

* `POST /buy/offers`
* `POST /buy/offers/{offer_id}/counter`
* `POST /sell/offers/{offer_id}/counter`
* `POST /buy/deals/{deal_id}/inquiries`

When the queue takes the write, the API answers `202` with `data: { status: "held", kind, hold_id, held_at }`. `kind`
names the held write: `offer`, `inquiry` or `address_request`. The schema also lists `deal`, and no deal operation
answers `202` today. `hold_id` is the id of the hold, with the prefix `hld_`. `held_at` is the instant the queue took
the write.

The write then waits for a person at Investorlift. Staff release or refuse it within one business day. The
counterparty does not see the write until staff release it.

Both sides get `offer.held` and `inquiry.held` on the events feed and on a webhook, and the event carries the same
`hold_id`. The writer of the held write gets the event. The seller of the deal gets it when a per-deal ceiling holds
the write, and that event names no buyer and no terms.

Four things send a write to the queue: a per-deal ceiling, a cold start, an anomaly, and strikes. An anomaly is a burst
of 5 times your own baseline over the trailing 14 days. The baseline tracks deal rows served, write rate, decline rate,
distinct deals touched and contact fields served. Investorlift emails the account when it occurs.

## Strikes

A seller files a strike against a buyer who acted on one of its deals in the last 90 days, at
`POST /sell/buyers/{buyer_id}/strikes`. One organization files one strike per buyer. One strike changes no cap: it marks
the buyer for Investorlift staff. The strike carries an id with the prefix `stk_`. A second strike against the same
buyer answers `409 strike_exists`. A strike after the 90 days answers `409 strike_window_closed`.

Two strikes inside 30 days from unrelated organizations drop the buyer one tier for 7
days. Three route every new write of the buyer to the hold queue. A ban needs staff. A strike from an organization
Investorlift later suspends is void, and the tier comes back. `GET /me` shows the two rules as the facts
`strike_tier_drop` and `strike_hold` in `trust.facts`.

## What a seller controls

Read and change the controls at `GET` and `PATCH /sell/settings` under the scope `deals:write`. The API applies each
control at the offer preview and at the submit. Under `refuse`, the API never stores a refused offer. Under
`auto_decline`, the API stores the offer and declines it at once, and it appears in your offers with `decline_reason`.
A setting the body omits keeps what it holds.

| Setting                    | What it does                                                                                                                    | Default  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `require_verified_pof`     | An offer needs identity verification and a current proof of funds, `T2` or above.                                               | `false`  |
| `floor_percent`            | The lowest offer, as a whole percent of the asking price. 0 sets no floor.                                                      | `0`      |
| `floor_mode`               | `refuse` answers `422 below_floor` and stores nothing. `auto_decline` stores the offer and declines it at once.                 | `refuse` |
| `disclose_floor`           | The preview states the floor as `deal.floor_amount`. Off, the preview names no figure.                                          | `false`  |
| `api_offers_enabled`       | `false` makes every offer through the API answer `403 api_offers_disabled`.                                                     | `true`   |
| `financed_offers`          | `allow` takes every financed offer. `lender_only` takes one from a buyer with a linked lender. `refuse` takes cash offers only. | `allow`  |
| `template_only_tier1`      | A `T1` buyer sends a template inquiry only, with 140 characters of their own.                                                   | `false`  |
| `api_auto_share_address`   | The address auto-share of Mogul also applies to API callers.                                                                    | `false`  |
| `blocked_buyer_entity_ids` | The buyer legal entities this organization refuses offers from. No response names the block.                                    | `[]`     |

## The gateway limits

Beside the caps, the gateway at `api.investorlift.com` limits requests. A person gets 60 requests a minute and 5,000 a
day. A registered app gets 600 a minute and 50,000 a day across its users. Every request counts, refused or served.
Past a limit, the gateway answers `429 rate_limited` with `Retry-After`. A published figure you reach is not abuse.

## The 429 bodies and `GET /me`

| Code                    | Trigger                                                                                        | `Retry-After`                         | The body names                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| `429 daily_cap_reached` | You spent the day's budget of an action, for example the deal budget or the draft cap.         | The seconds to the next midnight UTC. | `action`, `tier`, `limit`, `used` and `resets_at`.                           |
| `429 cap_reached`       | Your tier allows none of the action, so the cap is 0.                                          | The seconds to the next midnight UTC. | `action`, `tier`, `limit`, `used` and `resets_at`.                           |
| `429 cap_reached`       | The active-chains cap of your tier, or the per-deal offer ceiling on an offer the seller logs. | `3600`.                               | The cap in `cap`, or the ceiling in `deal_ceiling`, with `limit` and `used`. |
| `429 duplicate_inquiry` | A second inquiry, or a second address request, on one deal in 24 hours.                        | `86400`.                              | `deal_id` and `type`, with `limit` and `used`.                               |
| `429 rate_limited`      | The gateway's per-minute or per-day request limit.                                             | The seconds to wait.                  | Nothing beyond the problem members.                                          |

`GET /me` prints `trust.tier`, `trust.facts`, `trust.next_step` and one `caps` row per action with `limit`, `used`,
`remaining` and `resets_at`. The buy-side actions are `deal_read`, `preview`, `offer`, `inquiry`, `address_request` and
`seller_read`. The sell-side actions are `draft` and `contact_row`. Read it before a batch, and read it again after a
`429`. [Errors](/marketplace/concepts/errors#cap_reached) has the recovery sentences.


## Related topics

- [Errors](/marketplace/concepts/errors.md)
- [Quickstart for buyers](/marketplace/quickstart-buyer.md)
- [Authentication](/marketplace/authentication.md)
- [What the API returns](/marketplace/concepts/what-the-api-returns.md)
- [Access to the private beta](/marketplace/access.md)