Automatic Tier Upgrade

The automatic-tier-upgrade plugin moves your users between account tiers on a schedule. You set requirements for each tier, such as KYC, 2FA or trading volume, and the plugin moves up the users who meet them. It can also move users down when they stop meeting them. It's for operators who want tiers, and the fees and limits that come with them, to follow what users do without moving each user by hand.

If all you need is to move users up one tier when their KYC is approved, Tier Upgrade After KYC is simpler. See Which tier plugin to use.

What you need

• The Enterprise plan on HollaEx Cloud.
• Your tiers set up in Operator Controls → Exchange → Configuration → Tiers. See Tiers & Trading Fees.
• For a KYC requirement, a KYC plugin such as Automatic KYC. For an SMS requirement, an SMS plugin such as SMS via AWS SNS.

Set it up

1. Install the plugin. Go to Operator Controls → Exchange → Plugins, find automatic-tier-upgrade under Available to install and click Install.

2. Open its Admin view. All settings are in the plugin's Admin view, not in a settings form. Open it from the plugin's actions menu or from the Admin view tab on the plugin's page. It has the tabs Overview, Tier requirements, Settings and Last run.

3. Turn on Dry run first (recommended). On the Settings tab, turn on Dry run and save. Runs then record what would change without changing anyone. Upgrades and downgrades are on from the moment you install, so do this before you add requirements.

4. Set the requirements. On the Tier requirements tab, click Edit on each tier from tier 2 up. Tier 1 has no requirements: everyone starts there. Set tiers in order, because a tier needs requirements before the one above it can have any.

   Requirement	What it checks
   KYC verification	The user's identity verification is approved.
   Email verification	The user has verified their email.
   SMS verification	The user has a phone number on their account.
   Bank verification	The user has at least one approved bank account.
   2FA enabled	The user has two-factor authentication turned on.
   Minimum trading volume	The user's trading volume over the volume window, in your native currency.
   Volume window for this tier (days)	Overrides the window in Settings for this tier. Needs a trading volume requirement.
   Minimum account age (days)	How long ago the account was created.
   Minimum balance	The user's total balance across all assets, in your native currency. Assets without a price count as zero.

   Each verification can be required by one tier only. Trading volume, account age and minimum balance must not go down from a lower tier to a higher one.

5. Choose the run settings. On the Settings tab:

   Setting	What it does
   Schedule	How often the plugin runs: every 15 minutes, hourly (default), every 6 hours, or daily.
   Hour of day	For a daily run, the hour (0–23) in the exchange's email timezone.
   Dry run	Records what would change in the run report without changing anyone. Default: off.
   Trading volume window (days)	The period trading volume is counted over. Default: 30. A tier can override it.
   Trades that count	Maker and taker (default), maker only, or taker only.
   Markets that count	The markets whose trades count. Leave all unticked to count every market.
   Upgrade users	Turns upgrades on or off. Default: on.
   Upgrade to	The highest tier earned (default) or One tier per run.
   Highest tier granted automatically	Users are never moved above this tier. Leave empty for no limit.
   Downgrade users	Never, Only when trading volume drops (default), or When any requirement is lost.
   Downgrade by	One tier per run (default) or Straight to the highest tier still met.
   Never move users below tier	The lowest tier a downgrade can move anyone to. Default: 1.
   Exempt user IDs	Users whose tier is never changed.

   Settings take effect on the next run. A new schedule applies straight away.

6. Preview, then go live. On the Overview tab, click Preview changes to see who would move, from which tier to which, and why. Preview never changes anyone. When you're happy, turn off Dry run and save.

What your users see

Users don't see the plugin itself. They see their tier change, along with the fees and limits of the new tier.

When you save a tier's requirements, the plugin rewrites that tier's Requirements/Notes with a list of them, such as "KYC Verification" or "Minimum account age: 30 days". This replaces any note you wrote yourself.

How it works

• On each run, every eligible user is checked against the requirements of every tier and moved up or down according to your settings.
• Who is left alone: exempt users, subaccounts (their tier follows the main account) and unverified users are never changed. Flagged and deactivated users are not checked.
• Downgrades only look at the user's current tier. A user on a tier with no requirements is never moved down.
• If something is wrong, nothing changes. If the saved settings are invalid, or prices can't be fetched, the run stops without changing anyone and Last run says why. Fix the settings and save them again.
• If one user's change fails, the others still go through. The failure is listed in Last run.
• Last run shows when each run started and finished, whether it was a dry run, and its upgrades, downgrades, skipped users and failures.

warning

Users you moved to a higher tier by hand can be moved back down if they don't meet that tier's requirements under your downgrade setting. Add them to Exempt user IDs to keep them where they are.

Which tier plugin to use

	Automatic Tier Upgrade	Tier Upgrade After KYC
Moves users when	They meet the requirements you set per tier	Their KYC is approved
Requirements	KYC, email, SMS, bank, 2FA, trading volume, account age, balance	KYC only
Tiers	Any tier, up and down	One "from" tier to one "to" tier
Moves users down	Yes, if you choose	Never
Timing	On your schedule, from every 15 minutes to daily	Right after approval, with an hourly re-check
Setup	Admin view with requirements, schedule, preview and reports	Two settings

If you install both, make sure their rules agree. Otherwise a user moved up by one plugin can be moved back down by Automatic Tier Upgrade on its next run.

Troubleshooting

• Nobody is moving. Check that Dry run is off and Upgrade users is on, and that the tiers above have requirements. A tier without requirements stops upgrades going past it. Check Last run for a stopped run.
• "A run is already in progress". You clicked Preview changes while a scheduled run was still going. Wait for it to finish and try again.
• A user wasn't changed. Check whether they are exempt, a subaccount, unverified, flagged or deactivated.

Need help? Open a ticket from your HollaEx dashboard.