---
description: >-
Transaction and velocity limits per sender trust level — Tier 1 (basic), Tier 2 (verified), and Tier 3 (fully KYC'd) thresholds for daily and monthly transfers.
---
# Trust Level Limits
The Trust Level (Compliance Level) system controls how much a sender is allowed to transact. Higher levels require more KYC data and documents but unlock higher transaction limits across three rolling time windows: **24 hours**, **30 days**, and **180 days**.
***
### Checking Compliance Level
**Endpoint:** `GET /organizations/{tenant}/participants/{participantId}/complianceLevels`\
**Authentication:** Tenant-level (`x-api-key`)
```bash
curl --request GET \
--url https://{FQDN}/organizations/$TENANT/participants/$SENDER_ID/complianceLevels \
--header "x-api-key: $API_KEY"
```
This endpoint returns:
* The participant's **current compliance level** and its limits
* The **next available level** and its required fields
* The fields the participant is **still missing** to reach the next level
***
### Sample Response
A participant at `LEVEL_0` (cannot transact yet) with upgrade path to `LEVEL_1`:
```json
{
"participantId": "48066496-9445-41b7-acbe-85e069a77cb7",
"currentComplianceLevel": {
"level": "LEVEL_0",
"limits": {
"oneDayLimit": { "amount": "0.00", "currency": "USD" },
"thirtyDaysLimit": { "amount": "0.00", "currency": "USD" },
"oneHundredAndEightyDaysLimit": { "amount": "0.00", "currency": "USD" }
},
"requiredFields": [],
"perTransactionFields": []
},
"nextComplianceLevel": {
"level": "LEVEL_1",
"limits": {
"oneDayLimit": { "amount": "2999.00", "currency": "USD" },
"thirtyDaysLimit": { "amount": "6000.00", "currency": "USD" },
"oneHundredAndEightyDaysLimit": { "amount": "9999.00", "currency": "USD" }
},
"requiredFields": [
"firstName",
"lastName",
"phoneNumber",
"residentialAddress"
],
"perTransactionFields": []
},
"missingFieldsForNextComplianceLevel": [
"phoneNumber",
"residentialAddress"
]
}
```
**Key fields:**
* `currentComplianceLevel` — the level the participant qualifies for right now (`LEVEL_0` with zero limits when no data has been provided)
* `nextComplianceLevel.requiredFields` — everything the next level requires
* `missingFieldsForNextComplianceLevel` — the subset the participant hasn't provided yet — drive your progressive-onboarding UI from this list
***
### Compliance Level Overview
| Level | Typical Required Fields | Description |
| ----- | ----------------------- | ----------- |
| `LEVEL_0` | (none) | Default level. **Cannot transact.** Participant exists but has not provided minimum KYC data. |
| `LEVEL_1` | firstName, lastName, address, phoneNumber, ID Number, DOB | Basic KYC. Enables standard transaction volumes. |
| `LEVEL_2` | SSN/ITIN, occupation, document ID upload | Enhanced KYC. Unlocks higher limits. |
| `LEVEL_3` | Proof of source of funds | Full KYC. Maximum transaction limits. |
> **These levels are customizable per tenant.** Your specific required fields and limits are defined during the Inyo onboarding process and may differ from the defaults shown above.
***
### Checking Transaction Limits & Usage
To see how much of their limit a sender has already used:
**Endpoint:** `GET /organizations/{tenant}/fx/participants/{participantId}/limits`\
**Authentication:** Agent-level (`x-api-key` + `x-agent-id` + `x-agent-api-key`)
```bash
curl --request GET \
--url https://{FQDN}/organizations/$TENANT/fx/participants/$SENDER_ID/limits \
--header "x-api-key: $API_KEY" \
--header "x-agent-id: $AGENT_ID" \
--header "x-agent-api-key: $AGENT_KEY"
```
**Sample Response:**
```json
{
"oneDayLimit": {
"limit": { "amount": "2999.00", "currency": "USD" },
"used": { "amount": "500.00", "currency": "USD" },
"available": { "amount": "2499.00", "currency": "USD" }
},
"thirtyDaysLimit": {
"limit": { "amount": "6000.00", "currency": "USD" },
"used": { "amount": "2959.99", "currency": "USD" },
"available": { "amount": "3040.01", "currency": "USD" }
},
"oneHundredAndEightyDaysLimit": {
"limit": { "amount": "9999.00", "currency": "USD" },
"used": { "amount": "5000.00", "currency": "USD" },
"available": { "amount": "4999.00", "currency": "USD" }
}
}
```
**Key fields:**
* `limit` — Maximum amount for this time window (from the participant's current compliance level)
* `used` — Amount already consumed in the rolling window (only transactions that count toward limits — declined/cancelled ones don't)
* `available` — Remaining capacity (`limit - used`)
The limits reported here stay in lockstep with `GET /participants/{id}/complianceLevels` — both endpoints answer with the same numbers, and `available` is computed with the same rules the transaction validator applies.
***
### Upgrading a Sender's Level
To move a sender from one level to the next:
1. **Check current level** — `GET /participants/{id}/complianceLevels`
2. **Identify missing fields** — Look at `missingFieldsForNextComplianceLevel`
3. **Collect the data** — Update the sender's profile with the missing fields:
* Use `PATCH /people/{personId}` for profile fields (SSN, occupation, etc.)
* Use `PUT /people/{personId}/address` for address updates
* Use document upload endpoints for ID documents and source of funds
4. **Verify the upgrade** — Call the compliance levels endpoint again to confirm the level increased
```mermaid
flowchart TD
L0["LEVEL_0
cannot transact"] -->|"+ name, address"| L1["LEVEL_1
standard limits"]
L1 -->|"+ SSN, documents"| L2["LEVEL_2
enhanced limits"]
L2 -->|"+ proof of funds"| L3["LEVEL_3
maximum limits"]
```
***
### Use Cases
* **Progressive onboarding** — Start with minimal data (Level 1) and prompt for more only when the user needs higher limits.
* **Limit warnings** — Show users their remaining capacity before they initiate a transaction.
* **Upgrade prompts** — When a transaction would exceed the current limit, show exactly which fields are missing and guide the user to complete them.
* **Compliance dashboard** — Display a visual progress bar showing the user's level and what's needed for the next tier.
***
### Tracking Document Review
To show users that their documents are under review, subscribe to the `DocumentUpdatedEvents` [webhook](../webhooks.md) — it covers both KYC verification sessions and uploads. Either flow can also be polled: [read the session](uploading-documents.md#get-a-verification-session) for a KYC verification, or [verification status per document](uploading-documents.md#document-verification-status) for an upload. Neither poll covers the other flow.