3.1.0

Buyback Program

An Alliance Auth app for creating buyback programs and to allow users calculate prices for buyback contracts. Designed to be very transparent for the user and fast to use for the managers.

Contents

• Images
• Features
• Installation
• Program Settings
• Troubleshooting
• Change Log

Images

Features

• Authenticated or Public access*
• Multiple programs with their own settings
• Multiple owners
• Supports corporation and character owners
• Flexible program settings:
  • Allow all items
  • Allow only specific items
  • Custom location names
  • Global program tax
  • Item specified tax
  • Hauling fuel cost
  • Dynamic low price density tax
  • NPC price for NPC buy orders
  • Static prices per item
  • Manual review watchlist for items or groups
  • Use refined rate for meta 1-4 items
• Best price variant for ore:
  • Supports raw, compressed, refined and any combination of the 3.
  • Will calculate price by the best available pricing method
• Allow / disallow unpacked items
• Restrict program to:
  • States
  • Groups
  • Open for everyone
• Personal buyback static tracking for:
  • Outstanding contracts
  • Finished contracts
• Program tracking for owners:
  • Outstanding contracts
  • Total bought value
• Contract abuse checker and notifications
  • Check if items do not match the calculated contract
  • Check if price does not match the calculated contract
  • Check if contract is made at wrong location
  • Check if contract is made incorrectly to corporation or character
  • Check extra characters in contract title
  • Check if contract contains donations
  • Check for scam contracts mimicing buyback contracts
• Contract tracking history
• Supports base price sources from:
  • Fuzzwork API
  • Janice API
  • Use buy, sell or split price as source
  • Use 5% top average or instant prices for source
• Supports discord notifications
  • Notifications for accepted contracts
  • Notifications for new contracts
  • For aa-discordbot
  • For discordproxy
• Reverse buyback programs:
  • Owner lists items available for purchase from their hangar
  • Players submit buy requests and receive a tracking number
  • Stock automatically synced from ESI corporation assets
  • Supports public access without login
  • Restrict visibility to groups and states (same as normal programs)
  • Manager program statistics page showing all buy requests
  • Individual contract detail pages with item comparison and notifications
• Security:
  • Tracking detail pages restricted to issuer and managers by default
  • Group and state visibility restrictions on all program types
  • Ownership checks on all management actions

Installation

Step 1 - Prerequisites

1. Buyback program is a plugin for Alliance Auth. If you don't have Alliance Auth running already, please install it first before proceeding. (see the official AA installation guide for details)
2. Buyback program needs the app django-eveuniverse to function. Please make sure it is installed, before before continuing.

Step 2 - Install App

1. Activate your venv source /home/allianceserver/venv/auth/bin/activate
2. Install the plugin pip install aa-buybackprogram
3. Add 'buybackprogram', into your settings/local.py installed apps section
4. Run migrations python manage.py migrate
5. Collect static files python manage.py collectstatic
6. Reload supervisor

Step 3 - Update EVE Online API Application

Update the Eve Online API app used for authentication in your AA installation to include the following scopes:

• esi-contracts.read_character_contracts.v1
• esi-contracts.read_corporation_contracts.v1
• esi-universe.read_structures.v1
• esi-wallet.read_corporation_wallets.v1
• esi-corporations.read_divisions.v1
• esi-assets.read_corporation_assets.v1

Step 4 - Data Preload

Buybackprogram requires a lot of data to function as it is designed to allow your clients to sell you any items that exists in EVE. For this reason pre-loading all the date will take a while. Data pre-loading is used to decrease the amount of API calls made to type and price fetches.

Preload Load Type Data

To load type data run the command python manage.py buybackprogram_load_data. This will start the preload of all EveType, SolarSystem, EveMarketGroup and EveTypeMaterial objects.

You can follow the progress of the load from your auth dashboard. This task can spike up easily over 100.000 tasks at a time so it is very normal that the queue grows very large while running this task.

:warning: You will need to wait for the type data to load up before you can start to use the plugin. Trying to adjust program settings while the required data has not been yet loaded may result in failure of adjusting the settings.

Preload Price Data

After you have preloaded the type data you can preload price data into the database. Price data preloading is not mandatory but will speed up the first buyback calculations.

:information_source: If price information is not found for items when the prices are calculated the first time the prices for that item will be fetched during the calculation process. This will increase the calculation time for the contract.

To preload price data run python manage.py buybackprogram_load_prices

Step 5 - Configure Auth settings

Buyback program requires a few periodic tasks to operate and update its data.

Buybackprogram is designed to use locally stored prices to speed up the price calculations. It is important that you have the price update task in your periodic tasks so that your prices will update.

By adding the following lines in your local.py setting file the program will update the stored item prices at midnight. This same task is also responsible for maintenance tasks such as removing unlinked tracking objects, including reverse buyback requests that were never followed through with an actual contract (which releases the stock they had reserved). It will also check for any new contracts and update the statistics page with them every 30 minutes:

# Buybackprogram price updates, updates prices at midnight
CELERYBEAT_SCHEDULE['buybackprogram_update_all_prices'] = {
    'task': 'buybackprogram.tasks.update_all_prices',
    'schedule': crontab(minute=0, hour='0'),
}

# Buybackprogram contract updates, updates contracts every 30 minutes
CELERYBEAT_SCHEDULE['buybackprogram_update_all_contracts'] = {
    'task': 'buybackprogram.tasks.update_all_contracts',
    'schedule': crontab(minute='*/30'),
}

# Buybackprogram program performance updates, updates performance at midnight
CELERYBEAT_SCHEDULE['buybackprogram_update_program_performance'] = {
    'task': 'buybackprogram.tasks.update_program_performance',
    'schedule': crontab(minute=0, hour='0'),
}

# Buybackprogram wallet sync, updates wallet balances and names every hour
CELERYBEAT_SCHEDULE['buybackprogram_update_all_wallets'] = {
    'task': 'buybackprogram.update_all_wallets',
    'schedule': crontab(minute=0),
}
# Buybackprogram hangar stock sync, updates reverse buyback stock every 30 minutes
CELERYBEAT_SCHEDULE['buybackprogram_update_all_hangars'] = {
    'task': 'buybackprogram.tasks.update_all_hangars',
    'schedule': crontab(minute='*/30'),
}

Additional settings

You may change the following settings by adding the lines in your local.py setting files

Note: If you change your price source for an old install you need to wait for the price update task to run or manually run it to update your current database prices.

Note: Using Janice API, Jita 4-4 prices will be used with the top 5% average price of the 5 day median price for buy and sell orders. No other price sources can be used with Janice

Step 6 - Adjust Permissions

Overview of all permissions in this program. Note that all permissions are in the "general" section.

Step 7 - Program Setup

After you have preloaded all the needed data you can start to setup programs.

Each user with manage_programs permission is able to setup their own buyback programs.

Managers

Each buyback program is operated by a manager. To add a new manager click on the setup manager button.

Locations

Each buyback program operates at a location that is constructed of SolarSystem and a Custom name and an optional Structure ID. To add a new location click on the add location button on the buyback page.

Solar System & Name

Find a solar system by typing in the solar system box. Then determine a name for the structure. Most often you want to use the actual in-game name of the structure so that people are able to identify the location.

The solar system name will indicate your sellers where the program contract structure is located. The name will describe the structure name in where the contracts should be created and most often should be identical to the actual structure name in-game.

Structure ID

Structure ID is optional and will enable contract location tracking in the program statistics page. If a program location has been given a structure ID the statistics page will display a warning if the user has made the actual contract from some other structure than the one that was determined in the buyback program.

The easiest way to find the actual structure id is to link the structure name into any chat box and post the structure name into the chat. This can be done in any channel or the structure name can be also copied from any MOTDs.

After you have posted the structure name in the chat right click it and press copy. You can now paste the structure into notepad or any other text editor and your output should look like this:

[17:37:54] Ikarus Cesaille > <url=showinfo:35826//1037962518481>Oisio - LinkNet Central Station</url> `

The unique structure ID for your structure is then 1037962518481. Adding the ID to the location ID field will check if the contract creation location matches this ID.

Step 8 - Create Program

Once you have created a location and added at least one manager you can setup the actual program. Click on the create program button to create a new program.

Program settings

Each program can be customized based on your needs. When setting up select the settings you wish to use.

Name/Description

A display name for your program

Manager

This is the character or the characters corporation which will be used as the assign to target for buyback contracts at this location. To add more owners use the add manager button. You can only see your own characters.

Is Corporation

If you wish that the contracts are assigned to the owners corporation instead of the character tick this box.

Location

The location where contracts should be created at. Only these locations are accepted

Expiration

Expiration time the contracts should bet set to.

Price type

You can select what price type is used as the base price for your calculations. You can select from either buy, sell or split prices.

Default tax

This is a general tax which is applied on all items in this program. If you wish to not allow all items in this program you can leave this to 0.

General tax is applied on all items sold via the buyback. You can add additional taxes on individual items or ban them from being accepted to the program once you have created the program.

Hauling fuel cost

You can add a fuel cost expense that is applied on each item sold via this program based on the volume of the item.

:information_source: This setting is aimed more to null sec buyback programs to make it easier to calculate your taxes and display your members the expenses you have when selling.

Price density modifier

You can use a price density modifier which will add a additional tax on items with low price per volume ratio such as T1 ships.

:information_source: This setting is aimer more at high sec buyback programs.

Ore volume based on compressed volume

Using this setting will calculate all items that can be compressed (mainly ore and ice) based on the compressed variant volume and use this volume instead of the raw volume to calculate the hauling and price dencity costs. This setting is mainly aimed at null sec where you might get raw ore sold to you but want to compress it before shipping as raw ore volume is very high and will cause high hauling costs.

Price density threshold

This is the lowest isk/m^3 ratio for items that are accepted to the program without the price density tax. Finding your own limits depends on your logistical department.

For example: Tritanium is 500 ISK/m³ @ 5 ISK per unit price. PLEX is 14,5Trillion ISK/m³ @2.9M per unit price.

Price density tax

This is the tax which will be applied to items with a price density below the price density threshold

:warning: You should avoid using both the hauling fuel cost and the price density modifier at the same time as their function is fairly similar.

Allow all items

If you wish to allow any types of items to be sold via this program keep this box ticker.

You can determine individual increased taxes or ban items from being accepted to this program after creating the program.

If you do not want to accept all items you can set this box to False. By doing this you will need to set up a tax for each item you wish to accept into the program individually.

Ore settings

Ore type items such as asteroid, moon goo and ice have additional pricing methods you can use. You can use a mix of any of the three pricing models.

:information_source: When using more than one pricing model the best price will be used as the buy value.

Use Refined value

If you wish to calculate ore buyback value based on the mineral values tick this box.

Use compressed value

If you want to use compressed value as a pricing method tick this box.

Use raw ore value

If you want to use raw ore value as a pricing method you can tick this box. Note that some ores such as Kernite and Moon Goo do not represent the real mineral value of the ores.

You can also individually ban raw ore types from the program. If you have an other option than the raw ore value selected the price will be calculated based on the other pricing models.

Allow unpacked items

Most often you want to buy only items that are packed. This will ensure that people do not sell items such as broken ammo crystals for you.

Refining rate

The refining rate is used in combination with the use refined value option.

Blue loot npc price

If you cant to use NPC buy order prices for blue loot (Sleeper loot) instead of Jita prices check this box. NPC price for these items will always be used even when Jita price would be higher.

Red loot npc price

If you cant to use NPC buy order prices for red loot (Triglavian loot) instead of Jita prices check this box. NPC price for these items will always be used even when Jita price would be higher.

Restrictions

You can restrict the visibility of the buyback programs to groups and states with the restriction options.

If no options are selected the program will be visible for everyone with the basic_access role.

:no_entry: Do not mix group and state restrictions as this may lead into logic error. If you need to mix then create a separate programs for them.

Discord DM messages

If you want to receive messages over discord for every new contract you can tick this box.

:information_source: Requires the aa-discordbot plugin or discordproxy app to work

Show list of items on discord message

This option will determine if a list of all contract items is added into the discord message description field. If you are accepting all items the list may become very long. If set to false will show a link to the tracking page instead.

Discord channel messages

You can send notifications about new contracts directly into the discord channel which is linked to AUTH,

:information_source: Requires the aa-discordbot plugin or discordproxy app to work

Program wallet

This wallet information will be displayed on the tracking page allowing you to see your selected wallet balance when checking on outstanding contracts.

Use reprocessed value for T1/Named (Meta 1-4)

You can value T1 (meta 1-4 items) with refined output instead of the actual item price.

T1 Material refining yeld

Similar to ore reprocessing yield you determine the T1 (meta 1-4) item refining yield. This only applies if the Use reprocessed value for T1/Named (Meta 1-4) option is selected.

Public Program

If you want to allow unauthenticated users (people without an Alliance Auth account) to view and use this buyback program, tick the Public program box.

Public programs will be visible on the buyback index page without login and can be used to calculate prices without authentication. A tracking number is still generated for public submissions so that contracts can be linked to the calculation — the issuer will simply show as an anonymous user in the statistics page.

:warning: Public programs bypass all group and state restrictions. Any person with access to your Alliance Auth URL will be able to see and use the program. Do not use this together with group or state restrictions.

:information_source: Enabling public programs requires a one-time server configuration by your Alliance Auth administrator. Add the following to your local.py:

APPS_WITH_PUBLIC_VIEWS = ["buybackprogram"]

Without this setting, the public view will not be accessible even if the program is marked as public.

Step 9 - Special Prices

You can modify individual item settings or allow items for a program that has set allow all items = False via the special taxes menu for each program.

Set a item specific tax for each item. The tax wil be applied on top of the default tax for the program. You can also disallow an item from being accepted in the contract completely.

You can also set static prices. Items with static prices are absolute prices and have no taxes or price dencity costs added on them.

:information_source: The item specific tax can also be a negative value allowing you to decrease taxes on certain items.

To adjust individual item taxes inside a program click on the Special taxes button next to your program.

You can either add items one by one with the add item button or add all items that belongs to a market group and every sub-child market group of that group with add market group

You can edit an item on the taxation table simply by adding it again. To delete the item press the delete button next to it or to delete all items in the program click on the delete all items button.

Market Groups

When you add an market group each item inside that market group, the child of the market group and the child of the child group will be added to the item taxes (3 steps down)

The easiest way to check which items are under which market group is to open the market window in-game or third party programs such as https://evemarketer.com/

Example:

Market group Minerals is the bottom market group that includes the standard minerals. Adding this market group to the taxation will add 8 items to the taxes (Tritanium, Pyerite etc.)

Market group Standard ores is a parent category and there are no direct items under this category. However this category has child categories such as Veldspar, Jaspet, Scordite which each includes multiple variations of the ores. Adding the Standard ores category will add each ore type to the special tax section.

Step 10 - Manual Review Watchlist

To protect your buyback program from market manipulation or extremely low-velocity items (such as Officer Modules or rare Abyssal items), you can utilize the Manual Review Watchlist.

The Watchlist allows you to flag specific items or entire EVE Market Groups. When a user pastes an inventory containing a watchlisted item into the buyback calculator, the system will automatically:

1. Display a purple fa-search warning icon next to the item on the user's appraisal result.
2. Flag the generated tracking object.
3. Automatically attach a "Suspicious Contract" warning to the manager's Dashboard for that specific contract, ensuring the item is manually reviewed before the contract is accepted.

Adding Watchlist Rules

To manage your watchlist, click the Special Taxes button next to your program, and scroll down to the Manual Review Watchlist section. Click Add to Watchlist to create a new rule.

You have two options when adding a rule:

• Item Type: Start typing to search for a specific EVE item (e.g., "Estamel's Modified Invulnerability Field"). Only that exact item will trigger the warning.
• EVE Group: Start typing to search for a broader EVE item group (e.g., "Officer Modules"). Any item that belongs to this group will trigger the warning.

:information_source: Note: You can only specify either an Item Type or an EVE Group for a single rule. You cannot fill out both fields at the same time.

Deleting Watchlist Rules

To remove an item or group from the watchlist, simply click the Delete button next to the rule on the Special Taxes dashboard. The change takes effect immediately for all future calculations.

Most Common Groups

Name | Includes | Items -- | -- Standard Ores | Normal ores from belts and anomalies | Veldspar, Hedbergite, Compressed Arkonor ... Moon Ores | Ores from moon mining | Cobaltite, Loparite, Pollucite Ice Ores | Ores from ice mining | Blue Ice, Dark Glitter, Compressed Blue Ice .... Minerals | Contains materials for refining Standard Ore | Tritanium, Pyerite .... Salvage Materials | Salvage from loot | Armor Plates, Trigger Unit, Ancient Radar Decorrelator ...

Step 11 - Reverse Buyback Programs

Reverse buyback programs allow you to sell items from your corporation hangar directly to players. Players submit a buy request, receive a tracking number, and you create a contract to them with the requested items.

Creating a Reverse Program

Click Reverse Buyback in the navigation menu, then click 1. Create Reverse Program.

Settings

Name

A display name for the reverse program.

Manager

The character or corporation used as the contract issuer.

Is Corporation

If ticked, contracts will be issued from the manager's corporation.

Location

The structure where stock is held and contracts will be created. The structure ID must be set on the location for hangar sync to work.

Stock Source

Choose where the program's stock comes from:

• Whole hangar division — everything in the selected Hangar Division at the program locations is for sale.
• Selected containers only — only the contents of the chosen containers are for sale. Use this when you cannot dedicate an entire division to buyback. Containers must be assembled and sitting directly in a hangar division at one of the program locations; nested containers are not supported. Give containers a name ingame so they are easy to pick from the list.

Containers are discovered during the hangar sync, so on a new manager the container list is empty until the first sync has run. Click Refresh Stock and reload the page if the list is empty. If a selected container is repackaged or moved away from the program locations it disappears from the program's stock and a warning is written to the log.

Hangar Division

The corporation hangar division to sell from. Only used when the stock source is a whole hangar division.

Containers

The containers to sell from. Only used when the stock source is selected containers.

Price Type

The base price type used to value items. Default: Sell.

Sell Markup %

A markup percentage added on top of the base price.

Expiration

Expiration time for contracts created by the owner.

Public Program

If enabled, the program is visible and usable without login. Requires APPS_WITH_PUBLIC_VIEWS = ["buybackprogram"] in local.py.

Syncing Stock

Once your program is created, click Refresh Stock in the management menu to pull current hangar contents from ESI. Stock will also update automatically every 30 minutes if the celery beat task is configured.

:information_source: Only items located at a structure with a configured Structure ID will be synced. Make sure your location has a structure ID set.

How it works for players

Players navigate to Reverse Buyback, click Buy on a program, paste a list of items they want, and submit. The calculator checks availability against current stock and generates a price and tracking number. The player then waits for the owner to create a contract to them using the tracking number as the contract title.

Troubleshooting

Contract updates stop running after a worker restart

Symptom: the log shows Starting all contract updates and Updating contracts for <owner> for each owner, but no Fetching all contracts for ... line follows and no contracts are linked.

Cause: each owner's contract update runs as a run-once task. If a worker is restarted while the task is running (for example right after applying migrations), the lock is never released and every following run is silently skipped until the lock expires. The lock is stored in the Django cache and expires after BUYBACKPROGRAM_TASKS_TIME_LIMIT seconds (2 hours by default).

To clear the locks immediately:

redis-cli -n 1 --scan --pattern "*qo_buybackprogram*" | xargs -r redis-cli -n 1 del