Mercenary work WIP

Mercenary work runs a bounty job: members get credited for hits on a target, at a price per hit that your server sets, straight from Torn's attack logs. No manual bookkeeping, and no real money changes hands through the bot.

Merc settings: who runs it, the merc role, price and commission

Everything that belongs to Mercenary Work as a whole lives on the website at /guild/{server id}/merc-settings (Merc settings, linked from your server's card):

Merc managers (shown here, picked under Access & roles, which only the owner and Manage Server can open): the roles that may start, stop and prepare jobs (/merc-start, /merc-stop, /merc-order, /merc-panel), make price offers on or reject tickets and use the Mercenary work pages here. The server owner always can. As soon as roles are picked, only these roles (plus the owner) count, the Duty roster does not. Pick none and the Duty roster roles run Mercenary Work, as before. /merc-unregister, /merc-leaderboard and ordering through a ticket stay open to everyone. Registering a key and submitting hits are for members with the Merc role (below) and the managers only.
Merc role: pinged in the announcement that every new job posts in the channel it was started in ("Mercenary order #N received ... Join the thread to take part"). People from the role join the job thread themselves by clicking the thread link, nobody is pulled in. That announcement stays while the job runs and disappears when the job is closed (the "has ended" message stays). The thread itself never pings a role: the start call and the target alerts are an @here, which only reaches people who joined the thread, so everybody else can simply leave it. The Merc role is also the key to the job's buttons: only members with this role (and the managers) can register a key or submit hits; with no Merc role set, everyone can. /merc-start can still pick another role for a single job (mention_role), that one wins. A deleted role never blocks anything.
Default price offered when setting a price (optional): what the client pays for a counted hit (the gross price). /merc-start, /merc-order and the web orders use it when no price is given, and it is the suggested value in the Set price form of a ticket. Tickets can be opened without it, because a manager makes a price offer per request.
Commission (0 to 99 percent): what the house keeps. The mercenaries get price × (100 − commission) / 100, rounded down to whole dollars. Example: 20% at $500,000 means $400,000 per hit. Mercenaries only ever see their payout, never the price or the commission, in the thread, the hit lines, the standings or the results.

Clean the panel channel (off by default): the bot can tidy the channel where the order panel (/merc-panel) lives, every 5, 15 or 30 minutes, every hour, 6 hours or 24 hours. It deletes everything else in that channel, including messages from other bots: chat, old thread notices and announcements of finished jobs. It keeps the panel itself, pinned messages, anything younger than 5 minutes, and everything that belongs to a running job or an open ticket (the "thread created" notice and the announcement pointing to the job thread). When in doubt it keeps a message. Deleted messages can't be restored. The bot needs Manage Messages and Read Message History in that channel and an active Mercenary Work subscription; without them it deletes nothing and the page shows the problem next to the last cleanup time.

The commission is a snapshot: a running job keeps the price and commission it started with, a saved order keeps the commission from the day it was saved, and a ticket takes the price the requester accepted and the commission of the moment they accepted it. Changing the settings later only affects new jobs. Managers see price, commission and payout on Merc orders, Merc control, the Mercenary history and in the Excel export.

Starting a job

/merc-start sets which outcomes count (hospitalize, mug, leave), and the target: a specific person or a specific faction. A target is required, there is no open "anyone" target (set exactly one of target_person and target_faction). The price is optional and is the price the client pays before commission; leave it out and the price from the Merc settings is used (with no price set anywhere you get a short message pointing you to the settings). Before anything is created you get an ephemeral confirmation with the price, the commission and the payout per hit, so you can cancel if something looks wrong. Only you see that preview, the thread shows the payout.

A mercenary job belongs to the whole server: no command asks for a faction, and hits from every faction with a Torn key on the server count automatically. The job lists all of those factions. Internally one of them runs the target alerts and the start call (the starter's own faction when it can be told, otherwise the only one, otherwise the one with the oldest key); that choice is invisible to your members.

Detection

Hits are verified purely through Torn's own faction attack log, the same data chain watch uses in its precise mode. This needs Faction API Access on the key behind the job; without it, /merc-start refuses outright. There is no counting fallback here the way there is for chain watch, a bounty needs to know exactly who hit and how.

Hitters register their own key

Only members with the server's Merc role and the Merc managers can do this (everyone can if no Merc role is set); anyone else gets a short private message naming the role.

To count, every hitter registers their own Torn API key, with the Register API key button in the job thread or with /merc-register. A key with Limited Access is enough (Full Access keys are rejected): the bot reads only your own attack log with it, which is also why hits made anonymously are counted. The key is stored encrypted, nobody can read it back, and /merc-unregister deletes it again at any time. Without a registered key your hits do not count, not even from the faction log. The bot also checks that the key belongs to the Torn account your Discord account is verified as.

Submit your hits

Press Submit hits in the job thread (or use /merc-submit) whenever you want your hits counted. Nothing is fetched automatically: the bot reads your own attack log, with your registered key, only when you press it, and anonymous hits only count after you did. You get a private answer with how many hits were counted and, for the ones that were not, a short reason (before the start, after the end, wrong target or result, already counted, limit reached). You can press it again as often as you like, with a short pause of 30 seconds between presses, and hits counted before are never counted twice. If you have no key yet, the button opens the key form first. Errors, such as a rejected key, show up as a private message only you can see.

Key not working? Submit your attack log

This fallback is switched off for now. The button and /merc-log only tell you so; use Submit hits with a registered key.

If your key is missing or broken, press Submit log lines in the job thread (or use /merc-log) and paste up to 10 lines from your Torn attack log, one per line, for example 04:32:58 - 04/10/26 You used 25 energy anonymously attacking X and hospitalized them (chain #1). Lines that fit the job count right away and are marked self-reported in the thread and in the standings: they must fall into the job's time window, use an allowed outcome, hit the job's target and not be counted already through a key or the faction log. Each person can have at most 20 self-reported hits per job, and you get one answer line per submitted line. A registered key is the better way: it counts everything automatically.

The job thread

Confirming creates a dedicated Discord thread for that job. A short announcement goes in the channel you ran the command in: it pings the Merc role and asks people to join the thread by clicking the link (nobody is added to the thread automatically). That announcement stays while the job runs and is removed when the job is closed. The full overview (factions, payout, target, allowed outcomes) goes as the first message inside the thread. Every credited hit posts its own line there, live, as it happens. The thread never pings a role, only @here (the start call and the target alerts), which reaches just the people who joined it: if a job isn't for you, leave the thread.

Below it the bot keeps one dashboard card with the job status, target, what counts, the payout per hit, hits so far, the time window, the top five hitters and the target status alert, plus the Register API key and Submit hits buttons. It updates itself and moves back to the bottom of the thread after a few new messages (or after someone submits hits), so the buttons are always at hand. When the job is closed the card goes away and the results follow. The bot needs the Manage Messages permission in the thread for that.

End time, hit limit and closing

An end time or a hit limit only stops the counting. The job stays open, so hitters can still submit hits made before the end time until an admin closes it. When the end time passes the bot posts "Time is up" in the thread (once); when the hit limit is reached it posts that counting stopped. /merc-stop then closes the job, posts the final payroll leaderboard and saves it to the history; any admin of the server can close any job, or an admin presses Close order on the website. /merc-leaderboard shows the current standings any time. If several jobs are running at once, both commands take an optional job number to say which one you mean.

Every ticket, prepared order and job on a server share one number series starting at 1. Ticket #17 becomes Order #17 (/merc-order id:17) and the job it starts is "Merc on … [#17]". Gaps are normal (a deleted order, a ticket that was never approved) and numbers are never reused.

Target status alerts

Every order has a person or faction target, so /merc-start can watch whether it becomes attackable and ping when that changes. Pick one watch mode: "anytime" (the default, no watching at all), "online" (ping as soon as the target shows online), or "offline" (ping once the target has been offline for at least a set number of minutes). There's also an option to ignore anyone currently abroad for either of the online/offline modes. Every time a target becomes attackable the bot posts its own ping message in the thread (an @here, which reaches the people who joined the thread); the current watch status and the list of attackable targets live on the dashboard card, which is moved below the newest messages.

Merc Orders

A full job configuration can be prepared in advance on the website at /guild/{server id}/merc-orders and started later in Discord with a single command, /merc-order id:, instead of retyping every option. The form includes an optional start and end time (DD/MM/YY HH:MM, TCT/UTC) and a hit limit, and every saved order can be edited afterwards, including the ones that came from a ticket. The list shows who requested each order, plus the price, the commission and the payout per hit. The price field is optional and pre-filled with the price from the Merc settings; the commission is taken from the settings when the order is saved. Neither the form nor the command asks for a faction: the job is server-wide.

With a target faction you can also list excluded players (Torn IDs, one per line) in the form: members you can't beat. They never trigger a target alert and hits on them don't count. The list is only edited on the website and the thread dashboard shows who is excluded.

Merc control: managing jobs on the website

Admins manage running jobs on the website at /guild/{server id}/merc-admin (Merc control), not in Discord. For every running job you see its status ("running", "time is up" or "limit reached"), the hit total and the list of credited hits with who made them and how they came in (the player's key, the faction log, or "self-reported"). A wrong hit can be taken out with Remove: the bot corrects the count within a few seconds and says so in the job thread. If a hit limit had stopped the counting and the job is below the limit again, counting resumes. Close order closes the job exactly like /merc-stop does: results in the thread, saved to the history, announcement in the original channel. After closing, hits can still be removed from the last 20 closed jobs, and the Excel and PDF export of the history reflects the change. Hits credited before this feature existed are not listed one by one.

The same page lists the Merc keys registered on your server, with their status (ok, rejected, no access or unused) but never the key itself, and lets you remove one. The bot stops counting that player within about 30 seconds.

Order mercenaries with a ticket

Anyone on the Discord server can request a job, even without being in your faction. An admin posts the order panel with /merc-panel; people press Order Mercs and the bot opens a private ticket thread, visible only to them, the admins and the bot. It asks step by step with buttons and small forms: who to hit (a person or a faction, by Torn ID, a target is required), which results count, an optional start and end time (DD/MM/YY HH:MM, TCT/UTC), the number of hits they want (required, at least 1) and when to be alerted about the target. There is no price question: after the requester submits, a manager sends a price offer in the thread (see below). The order button works even when no default price is set in the Merc settings. Everyone can have only one open ticket at a time (a ticket waiting for an answer to a price offer counts), and a request that is not submitted within two hours is deleted without a word. The wizard reminds the requester that the bot never sends money: payment is made manually in-game. The requester also gets a direct message when the ticket is approved or rejected, when the job goes live, when counting stops (end time or hit limit) and when an admin closes it; if their direct messages are closed, the bot mentions them in the ticket thread instead. When the order is closed, the requester is told how much of the prepaid maximum (max hits times the price) is left to refund, in the ticket thread and in that message. The mercenaries never see this.

Price offer: when the requester presses Submit, the admins see the order with Set price and Reject buttons (only merc managers can press them, see the Merc settings; a rejection can carry a reason). Set price opens a small form for the price per hit (a whole number; the default price from the Merc settings is filled in when one is set). The bot then pings the requester in the thread: "Price offer for order #N: $X per hit, max N hits, maximum total $Y. Accept or decline?". Only the requester can press Accept price or Decline price. If they decline, the managers are pinged and press Set price again with a new price, as often as needed. While an offer is open, the ticket is waiting for the answer (a second offer is refused until the requester answers, or the managers reject the whole order). The requester never sees the commission. Tickets that were submitted before price offers existed keep a fixed price and the old Approve button.

Accepting: Accept does not start anything: it saves the order with the accepted price, marked as a ticket order on the Merc orders page, and the bot says "Order #N prepared". The ticket thread stays open and now carries a Paid button. An admin presses it once the client has paid (in-game, the bot never sends money). Only then does /merc-order id:N start the order; before that it answers "Order not paid yet" and keeps the order. If the thread can no longer be reached, the Merc orders page shows whether the client has paid and has a Mark as paid button. Once the order has really started, the ticket thread stays open and the bot posts a note there (updates come by direct message, and the thread is deleted 120 minutes after the mercenaries are paid out, see below). A rejected ticket's thread is locked and archived as before. The server can hold at most 20 saved orders, so clear old ones if accepting reports the limit (the offer stays open and can be accepted again).

The whole flow: order (ticket) → price offer → client accepts → client pays → Paid → /merc-order starts the job → the job is closed (/merc-stop or Close order) → the final results appear in the job thread with a second Paid button. Press it once the mercenaries are paid out: the thread (and the client's order ticket thread) is then deleted after 120 minutes (the server operator can change that with MERC_PAID_DELETE_MINUTES). The results stay in the Mercenary history, which also shows when a job was paid out.

For admins: the bot needs the permissions Create Private Threads, Send Messages in Threads and Manage Threads. Servers that invited the bot earlier have to grant them by hand or use the new invite link from the setup page, the bot tells you what is missing.

Private ping (beta)

Every mercenary can switch on a private ping for an order: the Private ping button on the job's dashboard card. You then get a direct message whenever the target becomes attackable (the same watch as the thread alerts, so it needs a target on the order). It costs 1 Billfold (Torn item 1080) per mercenary and order, taken from your own balance. Before charging, the bot sends you a confirmation DM; if your DMs are closed for this server it says so and charges nothing, so open your DMs first. Pressing the button again switches the ping off (no refund); switching it back on for the same order is free. After five failed DMs in a row the ping switches itself off. The card only shows how many pings are active, never who.

Your private ping arrives about 30 seconds before the @here ping in the thread: that head start is what you pay for. Without any private ping on the order, the thread ping comes at once.

Everybody has their own balance, the same on every server, and it is not refundable. Only registered mercenaries (an API key registered on any server) can hold one.

To top up, send Billfolds in-game to the bot's payment account. /ping-balance shows your balance, your last five movements and where to send them. They show up within about a minute. If you send Billfolds from an account that is not registered, they wait for the operator to assign them, so register your API key first.

About the bounty money

The bounty shown to the mercenaries (hits times payout per hit) is a number for you to pay out yourselves in Torn, in-game. The bot never sends real Xanax or money for mercenary work, it only keeps score. A client who ordered through a ticket gets a closing message with what they owe: the price per hit times the counted hits.

Back to Help & wiki