Understanding and Using the Torn API

Disclaimer: I am not a staff member so this is not "official." Additionally, I have developed a number of scripts and programs that use the API, but I will be as unbiased as possible.

Staff: Yes, this is about the API, but it is not about "API Development," so it should not go in the API Development forums. This is intended as a guide for users wishing to learn more about the API.

Before we begin...

PURPOSE

The purpose of this is to help educate you on what an API is, how they work, and why they exist. From there we'll discuss the Torn API and its features. Finally, we'll discuss security and other additional snippets of information.

TERMS

I realize I may interchange terms a few times in this article. Basically, think back to this...
"provider," "service," "host" = Torn
"client," "script" = API script/program/tool
"user," "player" = You

On to business...

What is an API?

Literally, API stands for Application Programming Interface - but that doesn't really tell you much. In a sort, it's a way for one program or service to do something with information from another program or service. Sort of a middle-man, with limitations and rules.

I recently saw a video that equated an API to a server at a restaurant. When you go to a restaurant you are presented with a menu to order food from, and your goal is to pick something from the menu and have the kitchen prepare it so you can eat it. The restaurant server is what takes your order from the menu and presents it to the kitchen, and then takes your completed food from the kitchen back to you to eat. In the same way an API accepts requests for information and asks the host program for that information, then returns that information to you.

To break this down using the Torn API as an example - A script may need to know the current price of a lion plushie, so the script says "Yo, API, what's a lion plushie cost?" and the API takes that question to the Torn servers which then respond with the price, and the API then comes back to the script and says "20 thousand bucks, dawg." Forgive the crude humor, but that's the gist of it.

Why do APIs exist?

Ultimately, they exist so someone else can do something with something someone else made. For Torn, it's so that independent developers can make scripts and programs that use information from Torn. For a hotel (random example), it's so that travel websites can see what rooms are available on what days.

Why use an API and not just get the data directly?

Well, there's a lot of reasons. For one, a service can't just open up their database for the world to read - some information may be private or incomplete. And, it would be horribly inefficient - the host would need to train every third-party how to use their internal database(s) and software.

A service, such as Torn, can choose information they want to be publicly available. There's tons of private data and even "hidden stats" - such as your crime experience - that they simply don't want out there. Plus there's information that is either delayed or manipulated before being released publicly to prevent abuse. An API allows the service to choose what information is available, and how it is delivered. This allows third-parties to independently create tools and resources that use the service's information. Like Torn, many services that provide an API don't care, test, or review what third-parties create - the service is already in control of and limiting what information is shared, so beyond that, it's all fair game.

What is an API key?

An API key is sort of like a username and password combo. It not only identifies the user or script/program that's requesting the information, but it also grants permission to actually use the API. In most cases, including Torn, the API key is provided by the service and cannot be selected by the user.

Torn's API

Torn's API shares a lot of information - ranging from your individual player information (battle stats, work stats, properties, money, messages, events, etc.), city information (stocks, items, bazaars, prices, education courses, company perks, etc.), faction information (members, attack history, news, perks, etc.), company information (employees, prices, stock, perks, etc.), and much MUCH more. The API can only provide information that is already available elsewhere in Torn - such as player stats, items, city info, etc - so it doesn't provide any "extra" information, just a different (and potentially more efficient) way to get it.

Torn's official API documentation can be found here, along with a demo page so you can see all the possibilities of what information is available and what gets returned from the server.

It's also interesting to note that the API, and the information provided by the API, is available at any time. Meaning that even while you are in jail, the hospital, traveling, etc., you can still get all the same information - which makes it very powerful, depending how you use it.

Your Torn API Key

Your Torn API Key can be found in your preferences by clicking the gear icon in the top-right of the Torn webpage, then choosing "API Key" from the menu. This is also where you can reset your API Key.

The API is Read-Only

The API is read-only, meaning it can only GET information from Torn, it cannot write (add or change) information.

Torn API Security

As previously mentioned, your API Key works sort of as a username and password combo - not only identifying who you are, but also giving you permission to use the API. In this way you can use your API Key to get your battle stats but not somebody else's.

Any legitimate API script or program will ONLY need your API Key. DO NOT give your Torn username, email address, or password to anyone or enter it into any website, script, or program.

Some third-party services that use the Torn API, such as TornStats, have you create a username and password - please note that this is perfectly fine, and it's asking you to provide a unique username and password for TornStats - it is NOT asking for your Torn username and password, it's asking you to create a username and password for their specific site. Please be vigilant to recognize the difference.

This seems as good as place as any to mention that the Torn API CANNOT get your email address or password. Your username and ID (McNeo [864688]), yes (which is already public information anyway) - but your login credentials (email and password), no.

Note: When I previously referred to an API Key as a sort-of username-password hybrid, please note that it has nothing to do with your actual username and password - it's completely independent and unrelated. Example... If your username is "abc" and your password is "123" your API key might be "R6d4M89a" (or any other random string) - your API key is NOT any sort of hash or equation using your ACTUAL username and password - it's a totally independent, random, bullshit string of text.

Can the Torn API and my API Key be used against me?

Short answer, yes - but it's not as bad as you may think, please read on.

First, as mentioned earlier, the API does NOT have access to your login credentials (email address and password) - secondly, again as previously mentioned, it is read-only, so nothing can actually be changed.

Anyone who has your API key can see all the same stuff you can - battle stats, money, messages, events, trades... Really though, unless someone is hardcore stalking you with a serious vengeance, the worst someone could or would do is get your battle stats and money information and share it.

If you feel that your API key has been compromised or used without permission you can reset it in your preferences by clicking the gear icon in the top-right of the Torn webpage, then choosing "API Key" from the menu, and clicking the "reset" button. This will change your API key and EVERYTHING you've entered your API key in to will stop working - after resetting you API key be sure to update any services you actually use and trust with your new key.

It's important to trust where you put your API Key. Some things to consider:

• Is the person who created this program/script well-known?
• Is this program/script used by a lot of people?
• Does this program/script have good reviews?
• Is the creator open about their intentions and purpose of the program/script?

Something worth adding here, for security reasons, is to understand that userscripts (things used in TamperMonkey, GreaseMonkey, etc.) are WAY LESS SECURE than the API. Remember that the API is controlled by Torn - they control what information is shared and how it is shared - userscripts are completely independent and run simply by reading and manipulating the information on your screen. This means that, yes, userscripts CAN get your email address, password, secret brownie recipe, etc. Fortunately, userscripts are mostly open-source, so it's hoped that someone somewhere actually looks at it and they would speak up if they see something wrong.

Please don't misinterpret my intention here... I personally use a number of userscripts - they're not bad or untrustworthy - but again, take care of what you trust and who you share your information with.

Unfair Advantage

A popular subject of the Torn API is creating an unfair advantage that some players may have over others. This is probably the most talked-about thing regarding the API and - as much as I hate to discuss it - I feel I must add something about it here.

First, consider the difference between "advantage" and "unfair advantage." There's a number of things that may give a player an advantage over another - the most obvious may be age, level, and stats; but there's also the user's activity level and what time of day they access Torn to consider. YOU, yes YOU, in one way or another, have a number of advantages over other players - as they do over you. That's what makes this a competitive game, and not just a race to the top of a database.

There's a ton of scripts and programs out there - some that use the API and some that don't - that definitely create an "advantage." I mean, if they didn't create some sort of an advantage, then why would they even exist?

To date, as far as I know, no API script/program/tool has been blocked, questioned, or shot down by staff. Yes, an "unfair advantage" is possible - but so far, despite a number of questions and disagreements, Torn staff have not taken action against any of them.

It's also important to note that scripting is not a new thing, and it didn't start with the release of the Torn API. Scripting in Torn has been around, likely, since 2 days after Torn's inception. The key thing is that the API helps more clearly - but not perfectly - define what's legal and illegal. If anything, the API reduces the likelihood of an unfair advantage, because it allows more players to have more access to more things to help them play the game (rather than just the script-kiddies having the advantage).

And, again... The API can only provide information that is already available elsewhere in Torn - such as player stats, items, city info, etc - so it doesn't provide any "extra" information, just a different (and potentially more efficient) way to get it.

Please be respectful

This thread/post is of course going to start a discussion - that's the joys of a forum. If you have a question or comment on this, of course, feel free to post below. However, please consider starting your own forum thread if you foresee a longer or pointed debated on a specific subject. I'd like for this thread to not get locked, and live on to encourage the Torn API.



OP will be updated as needed to provide relevant information.

(reserved if needed)

swatsicle made a script that Heather denied because it was too unfair regarding being attacked
I was denied a script I made to pop in IRC when duke's life got too low
it seems some people get denied the same thing others are granted; it's an interesting system.. but it is there,so to speak
anything "automation" is denied
while something such as a stock/stat tracker is allowed

(in response to To date, as far as I know, no API script/program/tool has been blocked, questioned, or shot down by staff. Yes, an "unfair advantage" is possible - but so far, despite a number of questions and disagreements, Torn staff have not taken action against any of them.)

Swatsicle made a script that automatically brought up the travel screen if the user was being attacked. This automation was deemed illegal. So, two points to make on this...
1. An API script/program cannot automate anything - the user must initiate the action. For example: If a player is under attack and the travel page automatically opens, this is illegal - But if a player is under attack and a popup appears that says "Your health dropped, you're probably under attack, do you want to travel?" and the player clicks "yes" and that brings them to the travel page - that IS legal.
2. This script did not use the API, it scraped a specific page which I will not share.

Now, on to the idea of a script that tracks Duke... This, actually, I would say is legal - and I base this on my own conversation with Heather, see screenshot below. The key thing is if it is available publicly to all players, and that it doesn't automate anything.

[image: s32.postimg.org]

Good write-up. I think another important point to make is that the API only provides information that you can already get via just clicking around Torn. Stats, prices, logs, etc ... it doesn't provide anything new, just provides it in a different format.

The one difference is that it can provide that info no matter your player status, like getting market prices while you're traveling.

Nice guide, nice examples, easy enough for newcomers to understand (thanks to your restaurant example)

R+

Someone can use your api key and see everything you can see though which is the way it can be abused and that's a pretty big issue as it makes it easy to track stats vs money on hand, in bank/vault, trades etc. Putting it in the op as just "The worst someone could do is get your battle stats and money information and share it." is a bit disingenuous, yes it's not going to auto send your items or money to someone else but you can be monitored for farming.

... which is why you should only give your API key to someone you trust, and if you suspect anything improper then reset your key and move on. Really that's the end of the discussion as far as Torn is concerned.

I give my key to TornStats, Torn Tools, and DoctorN. And I use if for some of my own very basic scripting that I'm learning. Giving out my API key is still way more "secure" than installing a userscript or entering my username and password into an app, imo.

McNeo (I'm pretty sure it was him) has made a suggestion that Torn provide everyone with their API history somehow, to include calls and IP addresses, which would allow anyone to monitor how their key is used. Implementing that would quiet any concerns of improper use. I'll try and find that and link it.

As I said "someone could get your information and share it" - providing the example that they could monitor you as a farming target is just one of thousands of things someone could do by "getting your information and sharing it." So, while I don't disagree with you, I opted not to list a thousand examples of how your information could be misused, just as I didn't list a thousand examples of how the API could be legitimately used. Point is, don't give you key to players you don't trust, and don't stick it into scripts or programs you don't trust.

It should be noted that, of the three, only TornStats is inherently safe (as long as you don't use their userscript).

Of course I do trust all of them and consider them safe, but both DoctorN and Torn Tools require massive trust compared to third-party web sites. You may feel safer for using an API key, but the reality is that, for them, there's no difference from asking for your password.

Both of them could steal your account, and TT could, on top of that, harm your computer.

This is true, downloading and running an executable is typically frowned upon unless you know where it came from. Big software companies have earned their trust over the years, I'm just a random individual, but hopefully I've earned that trust - which it seems I have, the download count on the Web server can't lie lol.

And as you say, even DoctornN - being a chrome extension - presents the same potentials as a user script for getting other information, even from outside of Torn.

It all boils down again to knowing who to trust. Fortunately, I haven't yet seen anything malicious from anyone on the api forums, so that's good.

bump

Would be nice to reference this to those who think scripting is illegal *cough* sweeney_todd *cough*

It's beginning to bother me that people keep saying this scraped a page, because it didn't.
I have the code to the script, it uses the API, as I've stated many times to others who think what Swat made was illegal.
:P

What difference does it make, mate?..

The script I'm thinking of scraped the page, perhaps we're thinking of different scripts - but no, the one I'm thinking of was definitely illegal. I won't discuss how it worked here since it's illegal, and I'd like to ask that you do the same. If you wish to continue the conversation about how you feel about the script, please consider starting your own thread, as it's clearly off topic from OP.

Interesting! i really should look at API but im too lazy and have been coasting in this game for years.

Rated+

100% don't like that someone could get alerted as soon as someone lands from traveling

It's been happening for years already with IRC bots and other apps that scrape torn.com webpages for data. Even in a logged out browser window I can see that you're Traveling to Canada right now, and if I had some app that checked this page every second and reported to me when that Status changed, it would have the same result as the API tool McNeo is proposing.
[image: image.prntscr.com]

At least with the API, these types of things are (more) out in the open, and can be used by non-scripters as well. There's some good talk about this here: https://www.torn.com/forums.php#!p=treads&f=63&t=15974299&b=0&a=0.