Overview

Augur is a decentralized prediction market platform that runs on Ethereum. For a detailed, high-level explanation of how Augur works, please refer to the Augur whitepaper.

If you want to use or help test Augur, please install the Augur App. If you want to use our cutting-edge development client, this is maintained at https://dev.augur.net. However, be warned – we push changes here pretty rapidly, so it can be a bit buggy!

Augur has its own dedicated Stack Exchange, which allows anyone to ask questions about Augur and get answers to those questions. It’s a great resource to find the answers for questions you might have that aren’t answered directly in these documents. Additionally, you can chat with us on Discord. If you’d like to join the conversation, just go to invite.augur.net and sign up. Most questions are best asked in the #dev or #general channels.

Getting Started

If you would like to help develop Augur, you’ll need to build the client from source. To do this, first install version 8 of Node.js (note that the version number is important), and Git.

Once this has been done, Augur’s dependencies will need to be installed. This can be done using npm or yarn. Both methods are detailed in the next sections.

If you plan on submitting a pull request to the Augur Project, please be sure to read through the Contributing section of these documents before submitting the request.

If you are using or helping to develop the Augur client (i.e., the front-end/user interface), it usually is not necessary for you to run a local Ethereum node on your computer. We’re already running several hosted nodes to which you can connect! If you are running an Ethereum node, the client will automatically detect it and begin talking to it; if you are not, the client will default to using the hosted nodes.

Using NPM

Node.js comes with a built in package manager called npm. (Again, please note that version 8 of Node.js is required for Augur.) npm is used to install dependencies for Augur, build the Augur project from source code, run tests, and start a web server to host Augur, among other things. To install Augur’s dependencies using npm, run the following command:

$ npm install

To build Augur from the source code, run:

$ npm run build

After building Augur from the source files, a local web server will need to be started. This can be done using the following command:

$ npm start

To enable hot-reloading (which automatically loads changes made locally), run the following instead of npm start:

$ npm run dev

Doing this is an easy way to do some hacking on the Augur source code and see the changes reflected in real time.

Now open a web browser and go to http://localhost:8080. This should load Augur’s most popular categories page.

Congratulations, you’re ready to start hacking!

Using Yarn

Some people prefer to use yarn instead of npm. To use yarn, execute the following command to install the Augur dependencies:

$ yarn

To build Augur from the source code, run:

$ yarn build

After building, the following command will start a local web server:

$ yarn start

To enable hot-reloading for development purposes, run the following instead of yarn start:

$ yarn dev

Finally, open a web browser and go to http://localhost:8080. This should load Augur’s most popular categories page.

Congratulations, you’re ready to start hacking!

Architecture

Augur is designed to work with a locally-running Ethereum node; however, if one is not available, Augur can be configured to use a hosted Ethereum node instead. A hosted Ethereum node is one that is hosted on a public server by the Augur development team. The sections below explain a bit about each setup and provide a diagram of what’s going on under the hood.

Local Ethereum Node

Running a local Ethereum node, such as Geth, while using Augur provides the best performance and overall experience. This is because Augur sends RPC requests to a hosted Ethereum node takes more time than sending them to a local node. To use a local Ethereum node with Augur, either download and run the Augur app locally, or simply visit https://dev.augur.net, which is configured to automatically talk to a local node, if present.

To use sendTransaction RPC commands (or any other command that requires Ether or is actually sent to the Ethereum network) the Ethereum node will need to unlocked. The easiest way to do this using Geth is to start it using the --unlock option:
geth --unlock 0 --testnet --rpc --ws --rpccorsdomain "http://localhost:8080" --wsorigins '127.0.0.1'
The --ws flag allows WebSocket connections, which are recommended for speed. The --rpccorsdomain and --wsorigins flags specify what domains are allowed to send RPC requests to your Geth node. Here http://localhost:8080 is whitelisted; this is the default address where the Augur UI client is served, if you build Augur locally. To use your local Ethereum node with a remote (hosted) Augur client, you will need to set --rpccorsdomain and/or --wsorigins to your host’s address; for example, if the remote host is at https://dev.augur.net, then you would use https://dev.augur.net for --rpccorsdomain and --wsorigins.

Note to Geth users: Since Geth’s RPC server uses regular (unencrypted) HTTP, the Augur app must also use regular HTTP to communicate with a local Geth node.

Hosted Ethereum Node

Since many users may not wish to go to the trouble of running a full Ethereum node solely to use Augur, the Augur development team maintains a public Ethereum node on the Rinkeby test network at rinkeby.ethereum.nodes.augur.net, which is used automatically by https://dev.augur.net.

Trading

Augur allows anyone to create an openly tradable Market about any upcoming event. Augur maintains an Order Book for each of the Markets created. Any trader can place or take an Order on the Market’s Order Book. When placing a trade, that trade request will be Filled immediately if there is an Order on the Order Book that will fulfill it. If there is no matching Order, or if the trade request can only be partially Filled, the remainder of what wasn’t filled of the trade will be placed on the Order Book as an Order. Order Creators may cancel their Order to remove it from the Order Book. Orders are executed on a “first come, first served” basis.

The Augur UI offers users the best prices first when displaying the Order Book on each Market page. Orders are never executed at a worse price than the limit price set by the trader, however they can settle for better than the limit price. Orders can also be partially filled. The UI will automatically include multiple backup/fallback Orders to attempt to fill the Order in the event that the best Order was filled before the transaction was sent. These backup/fallback Orders are always within the limit price set by the trader.

Trading Example

Let’s use an example Yes/No Market trading on the “super big event” coming up. For this example, we want to go long on Yes. We would submit a trade request to buy 100Shares of Yes with a limit price of 0.5 ETH, which will cost 50.0 ETH plus gas used to send the transaction.

If there are Orders on the Order Book that match our request for 100 Shares of Yes at a price of 0.5 ETH, or cheaper, then Augur will fill those Orders. We will now own 100 Shares of Yes and we will have lost 50.0 ETH plus gas cost.

If no Order is available on the Order Book that would partially or completely fill our trade request then a Bid Order would be placed on the Order Book. Whenever an Order is placed on the Order Book something of value is escrowed by the Market. In our example, the value we are giving to the Market to place our bid would be our 50.0 ETH. If we were attempting to sell Shares that we currently owned then we would escrow the Shares instead of ETH. If we cancel our Order we can get our 50.0 ETH back, the only currency lost would be the gas used to pay to place the trade and cancel the trade. When a Filler decides to fill our Order on the Order Book, we will get our 100 shares of Yes transferred to us.

For more information on how to trade using the Augur API, check the trade section of the Transaction API.

Settlement Fees Explained

Creating a Market costs a small amount of ETH. Without some incentive people won’t create Markets as they get nothing in return for the ETH they spent to create it. Augur solves this problem by allowing Market Creators to set a Creator Fee for their Market. The Creator Fee must be between 0 and 50 percent, and cannot be changed once a Market is created. In addition to the Market Creator Fee, Market Creators can profit via spread by providing liquidity to the Markets they create.

Augur also extracts Fees to help support the Reporting System known as the Reporting Fee. Settlement Fees refer to both the Creator Fee and the Reporting Fee combined. Unlike the Creator Fee, the Reporting Fee isn’t set by the Market Creator. Instead, it is set by an off-Augur price feed. Once the REP price is known, Augur can calculate the REP Market cap and the appropriate Reporting Fee to ensure the security of the Reporting System.

The Augur contracts will track the Open Interest of all Markets passively as people interact with Augur, which allows Augur to always have access to the Open Interest numbers. Once the Open Interest and REP market caps are known Augur can then determine wether the Reporting Fee is too high or too low. Augur then calculates the new Reporter Fee using the following formula:

current_reporting_fee * (augur_open_interest * 7.5 / rep_market_cap)

The Reporting Fee will be updated once every 7 days, or once every Fee Window. If updates were to occur too frequently, the Market will not have time to adjust to the new fees. If we update too infrequently, then we are at risk of the security model becoming invalid due to a sudden growth in Augur that isn’t yet accounted for by the fee system.

Settlement Fees are extracted anytime Settlement occurs and Shares are destroyed. This can happen for two reasons:

Selling a Complete Set can be thought of as exiting your market Position. Complete Sets are a set of Shares for each Outcome. Complete Sets are priced differently for each Market, and are determined by the Number of Ticks, which represents all possible price points, or Ticks, for a Market as well as the amount of attoETH it costs to purchase a Complete Set for the Market. If you own a set of Shares in each Outcome, you can Settle those Shares and receive ETH back for their value minus Settlement Fees.

Calculating Trades

In this section we break down all potential trade situations and their expected result. There are two types of Orders, Bid Orders (requesting to buy) and Ask Orders (requesting to sell). In our examples below we will go over all the potential trade possibilities around Bid Orders and Ask Orders. Orders are placed on the Order Book by Order Creators and contain four important details: The Creator of the Order, the price of the Order, The amount of Shares or ETH escrowed, and the Outcome we plan to trade on. The price can be any value between 0 and the Number of Ticks. The calculations below use num_shares as the number of Shares the Order is requesting, price as the price per Share for the Order, outcome for the Outcome our Order is trading on, num_ticks as the Number of Ticks, and fee_rate as the Settlement Fees extracted during the Settlement of Shares.

Reporting

Once a Market’s underlying event occurs, the Outcome must be determined in order for the Market to Finalize and begin Settlement. Outcomes are determined by Augur’s Decentralized Oracle, which consists of profit-motivated Reporters, who simply report the actual, real-world Outcome of the event. Anyone who owns REP may participate in the Reporting and Disputing of Outcomes. Reporters whose Reports are consistent with consensus are financially rewarded, while those whose Reports are not consistent with consensus are financially penalized.

Participation Tokens

During any Fee Window, REP holders may purchase any number of Participation Tokens for an equivalent amount of REP. At the end of the Fee Window, they may redeem their Participation Tokens for the same amount of REP, plus a proportional share of the Fee Window’sReporting Fee Pool. If there were no actions (e.g., submitting a Report or Disputing a Report submitted by another user) needed of a Reporter, the Reporter may purchase Participation Tokens to indicate that they showed up for the Fee Window. Just like Staked REP, Participation Tokens may be redeemed by their owners for a pro rata portion of fees in this Fee Window.

It is important that REP holders are ready to participate in Market resolution in the event of a Fork. The Participation Token provides an incentive for REP holders to monitor the platform at least once per week, and, thus, be ready to participate if the need arises. Even REP holders who do not want to participate in the reporting process are incentivized to check in with Augur once per 7-day Fee Window in order to buy Participation Tokens and collect fees. This regular, active checking in will ensure that they will be familiar with how to use Augur, will be aware of Forks when they occur, and thus should be more ready to participate in Forks when they happen.

Market State Progression

Augur Markets can be in seven different states after creation. The potential states, or “phases”, of an Augur Market are as follows:

Pre-Reporting

Designated Reporting

Open Reporting

Waiting for the Next Fee Window to Begin

Dispute Round

Fork

Finalized

The relationship between these states can be seen in the figure below:

Pre-Reporting State

The Pre-Reporting or trading phase is the time period that begins after trading has begun in the Market, but before the Market’s event has come to pass. Generally, this is the most active trading period for any given Augur Market. Once the event end date has passed, the Market enters the Designated Reporting Phase (state a in the figure above).

Designated Reporting State

When creating a Market, Market Creators are required to choose a Designated Reporter and post a No-Show Bond. During the Designated Reporting Phase (state a in the figure above), the Market’s Designated Reporter has up to three days to Report on the Outcome of the event. If the Designated Reporter fails to Report within the allotted 3 days, the Market Creator forfeits the No-Show Bond, and the Market automatically enters the Open Reporting Phase (state b in the figure above).

If the Designated Reporter submits a Report on time, then the No-Show Bond is returned to the Market Creator. The Designated Reporter is required to post the Designated Reporter Stake on its Reported Outcome, which it will forfeit if the Market finalizes to any Outcome other than the one they Reported. As soon as the Designated Reporter submits its Report, the Market enters the Waiting for the Next Fee Window to Begin Phase (state c in the figure above), and the Reported Outcome becomes the Market’s Tentative Outcome.

Open Reporting State

If the Designated Reporter fails to Report within the allotted 3 days, the Market Creator forfeits the No-Show Bond, and the Market immediately enters the Open Reporting Phase. As soon as the Market enters the Open Reporting Phase, anyone can report the Outcome of the Market. When the Designated Reporter fails to Report, the first Reporter who Reports on the Outcome of a Market is called the Market’s First Public Reporter.

The Market’s First Public Reporter receives the forfeited No-Show Bond in the form of Stake on their chosen Outcome, so they may claim the No-Show Bond only if their Reported Outcome agrees with the Market’s Final Outcome.

The First Public Reporter does not need to Stake any of their own REP when Reporting the Outcome of the Market. In this way, any Market whose Designated Reporter fails to Report is expected to have its Outcome reported by someone very soon after entering the Open Reporting Phase.

Waiting for the Next Fee Window to Begin State

Once the market receives its Initial Report it enters the Waiting for the Next Fee Window to Begin Phase (state c in the figure above). During this phase, Reporting for the Market is on hold until end of the current Fee Window. Once the next Fee Window begins, the Market enters the Dispute Round Phase.

Dispute Round State

The Dispute Round (state d in the figure above) is a 7-day period, during which any REP holder has the opportunity to Dispute the Market’s Tentative Outcome. (At the beginning of a
Dispute Round, a Market’s Tentative Outcome is the outcome that will become the Market’s Final Outcome if it is not successfully disputed by REP holders.) A Dispute consists of Staking REP (referred to as Dispute Stake in this context) on an Outcome other than the Market’s current Tentative Outcome. A Dispute is successful if the total amount of Dispute Stake on some Outcome meets the Dispute Bond size required for the current round. The Dispute Bond sizes are chosen in such a way to ensure a fixed ROI of 50% for Reporters who successfully dispute false Outcomes. Details for how the Dispute Bond size is computed can be found in the Dispute Bond glossary entry.

The Dispute Bonds need not be paid in their entirety by a single user. The Augur platform allows participants to crowdsource the Dispute Bonds. Any user who sees an incorrect Tentative Outcome can Dispute that Outcome by Staking REP on some Outcome other than the Tentative Outcome. If any Outcome (other than the Tentative Outcome) receives enough Dispute Stake to fill its Dispute Bond, the current Tentative Outcome will be successfully Disputed.

In the case of a successful Dispute, the Market will either undergo another Dispute Round or it will enter the Fork Phase (state e in the figure above). If the size of the filled Dispute Bond is greater than the Fork Threshold, then the Market will enter the Fork Phase. If the size of the filled Dispute bond is less than the Fork Threshold, then the newly chosen Outcome becomes the Market’s new Tentative Outcome, and the Market undergoes another Dispute Round.

All Dispute Stake is held in escrow during the Dispute Round. If a Dispute Bond is unsuccessful, then the dispute Stake is returned to its owners at the end of the Dispute Round. If no Dispute is successful during the 7-day Dispute Round, the Market enters the Finalized State (state f in the figure above), and its Tentative Outcome is accepted as the Final Outcome. A Market’s Final Outcome is the Tentative Outcome that passes through a dispute Round without being successfully Disputed, or is determined via a Fork. Augur’s contracts treat Final Outcomes as truth and pay out accordingly.

All unsuccesful Dispute Stake is returned to the original owners at the end of every Dispute Round. All successful Dispute Stake is applied to the Outcome it championed, and remains there until the Market is Finalized (or until a Fork occurs in some other Augur Market). All Dispute Stake (whether successful or unsuccessful) will receive a portion of the Reporting Fee Pool from the current Fee Window.

Fork State

The Fork Phase is a special state that lasts up to 60 days. Forking is the Market resolution method of last resort; it is a very disruptive process and is intended to be a rare occurrence. A Fork is caused when there is a Market with an Outcome with a successfully filled Dispute Bond of at least 2.5% of all REP. This Market is referred to as the Forking Market.

When a Fork is initiated, a 60-day Forking Period begins. Disputing for all other non-Finalized Markets is put on hold until the end of this Forking Period. The Forking Period is much longer than the usual Fee Window because the platform needs to provide ample time for REP holders and service providers (such as wallets and exchanges) to prepare. A Fork’s Final Outcome cannot be Disputed.

Every Augur Market and all REP tokens exist in some Universe. REP tokens can be used to Report on Outcomes (and thus earn fees) only for Markets that exist in the same Universe as the REP tokens. When Augur first launches all Markets and all REP will exist together in a Genesis Universe.

When a Market Forks, new Universes are created. Forking creates a new Child Universe for each possible Outcome of the Forking Market (including the Invalid Outcome). For example, a Yes/No Market has 3 possible Outcomes: A, B, and Invalid. Thus a Yes/No Forking Market will create three new Child Universes: Universe A, Universe B, and Universe Invalid. Initially these newly created Universes are empty: they contain no Markets or REP tokens.

When a Fork is initiated, the Parent Universe becomes permanently Locked. In a Locked Universe, no new Markets may be created. Users may continue trading Shares in Markets in Locked Universes, and Markets in a Locked Universe may still receive their Initial Reports. However, no Reporting rewards are paid out there, and Markets in Locked Universes cannot be Finalized. In order for Markets or REP tokens in the Locked Universe to be useful, they must first be migrated to a Child Universe.

Holders of REP tokens in the Parent Universe may migrate their tokens to a Child Universe of their choice. This choice should be considered carefully, because migration is one-way; it cannot be reversed. Tokens cannot be sent from one sibling Universe to another. Migration is a permanent commitment of REP tokens to a particular Market Outcome. REP tokens that migrate to different Child Universes ought to be considered entirely separate tokens, and exchanges ought to list them as such.

When a Fork is initiated, all REP Staked on all non-Forking Markets is unstaked so that it is free to be migrated to a Child Universe during the Forking Period.

Whichever Child Universe receives the most migrated REP by the end of the Forking Period becomes the Winning Universe, and its corresponding Outcome becomes the Final Outcome of the Forking Market. Un-Finalized Markets in the Parent Universe may be migrated only to the Winning Universe and, if they are un-Finalized and have received an Initial Report, are reset back to the Waiting for the Next Fee Window to Begin Phase.

There is no time limit on migrating tokens from the Parent Universe to a Child Universe. Tokens may be migrated after the Forking Period, but they will not count towards the determination of the Winning Universe. To encourage greater participation during the Forking Period, all token holders who migrate their REP within 60 days of the start of a Fork will receive 5% additional REP in the Child Universe to which they migrated. This reward is paid for by minting new REP tokens.

Reporters that have Staked REP on one of the Forking Market’s Outcomes cannot change their position during a Fork. REP that was Staked on an Outcome in the Parent Universe can be migrated only to the Child Universe that corresponds to that Outcome. For example, if a Reporter helped fulfill a successful Dispute Bond in favor of Outcome A during some previous Dispute Round, then the REP they have Staked on Outcome A can only be migrated to Universe A during a Fork.

Sibling Universes are entirely disjoint. REP tokens that exist in one Universe cannot be used to Report on events or earn rewards from Markets in another Universe. Since users presumably will not want to create or trade on Markets in a Universe whose Oracle is untrustworthy, REP that exists in a Universe that does not correspond to objective reality is unlikely to earn its owner any fees, and therefore should not hold any significant market value.

Therefore, REP tokens migrated to a Universe which does not correspond to objective reality should hold no market value, regardless of whether or not the objectively
false Universe ends up being the Winning Universe after a Fork.

Recall from the section on the Dispute Round State that any Stake successfully disputing an Outcome in favor of the Market’s Final Outcome will receive a 50% ROI on their Dispute Stake.

In the event of a Fork, any REP Staked on any of the Market’s false Outcomes
should lose all economic value, while any REP Staked on the Market’s true Outcome is rewarded with 50% more REP (via newly minted REP) in the Child Universe that corresponds to the Market’s true Outcome (regardless of the Outcome of the Fork). Therefore, if pushed to a Fork, REP holders who Dispute false Outcomes in favor of true Outcomes will always come out ahead, while REP holders who Staked on false Outcomes will see their REP lose all economic value.

Finalized State

A Market enters the Finalized State (state f in the figure above) if it passes through a 7-day Dispute Round without having its Tentative Outcome successfully Disputed, or after completion of a Fork. The Outcome of a Fork cannot be Disputed and is always considered final at the end of the Forking Period. Once a Market is Finalized, traders can Settle their Positions directly with the Market. When a Market enters the Finalized State, we refer to its chosen Outcome as the Final Outcome.

If the Designated Reporter does successfully Report within the Designated Reporting Phase, the No-Show Bond is refunded to the Market Creator immediately and the Market enters the Dispute Round Phase, which lasts for seven (7) days. During this 7-day period, any REP holder can Stake REP on an outcome other than the Tentative Outcome and receive a proportionate amount of Participation Tokens in return. The Participation Tokens allow the holder to collect fees at the end of the current Fee Window. The Staked REP goes toward filling the Dispute Bond for the Outcome on which it was Staked. If that outcome gets enough REP Staked on it to fill the Dispute Bond size, that Outcome becomes the new Tentative Outcome, and the Market returns to the Waiting for the Next Fee Window to Begin Phase (or Forks if the Outcome gets more than the Fork Threshold Staked on it). If the Market is left unchallenged for the duration of the Dispute Round Phase, then the Market’s Tentative Outcome becomes the Final Outcome and the Market is considered Finalized, allowing the Settlement of Shares.

Any fees collected by Augur during a given Fee Window are added to a Reporting Fee Pool for that Fee Window. The Reporting Fee Pool is used to reward REP holders who participate in Augur’s reporting process. At the end of the Fee Window, the Reporting Fee Pool is paid out to holders of Participation Tokens in proportion to the Staked REP they hold.

Markets are placed into the next available Fee Window once the Designated Reporter or First Public Reporter submits a Report. For example, if a Market’s Designated Report is submitted at 12:00 AM EST on January 3rd, 2053 and a Fee Window was just started on January 1st 2053, the Market would move into the next Fee Window that would be starting on January 8th, 2053, or 7 days since the start of the January 1st Window.

Any REP holder can participate in a Fee Window. In fact, in some cases, someone without any REP is able to successfully Report on Markets in the Open Reporting Phase. This case only occurs when the Market’s Designated Reporter fails to Report during the Designated Reporting Phase. In this situation, the first person to submit a Report can do so and Stake 0 REP on the Report. This is the true because the No-Show Bond is added to the First Public Reporter’s Stake, so in this case the Stake can be 0 as it will get the bond added to it. (The First Public Reporter must still pay the gas cost to submit the Report.) This creates a race to be the First Public Reporter so as to attempt to get free REP from reporting correctly and earning the No-Show Bond.

API Overview

augur.js is a JavaScript SDK that is the developer-facing component of Augur’s middleware. It is the recommended way to interact with Augur from a custom application, and it can be used to query for information about Augur’s Markets and interact with Augur’s back-end Solidity smart contracts, which can be found in the augur-core repository.

The documentation for augur.js is divided into four sections: the Simplified API, the Call API, the Transaction API, and the Events API. The Simplified API provides general information about Markets within Augur, and many of its functions require a connection to an Augur Node. The Call and Transaction APIs provide direct mappings to Augur’s smart contract functions via the augur.api object. The Call API uses eth_call to make “get” requests for information stored on the blockchain. The Transaction API uses eth_sendTransaction to make “set” requests to the blockchain in order to modify the blockchain’s information in some way, like creating a new Order on the Order Book. The Events API enables listening for certain logged events and searching for them. The Call, Transaction, and Events APIs do not require a connection to an Augur Node. Each of these four components of augur.js is covered in greater detail in their respective sections below.

This API Overview section explains how to add augur.js to a custom application and how to connect it to an Ethereum node and an Augur Node. It also covers how augur.js’ account management works, how numbers should be used in augur.js, how to load and create Markets, and debugging options.

Augur Node

Anyone wishing to query for information about Augur’s markets will need to use the augur.js Simplified API, which requires a connection to an Augur Node for many of its functions. Augur Node is a standalone application that scans the Ethereum blockchain for all Augur event logs and stores them to a SQLite or PostgresSQL database.

Instead of looking up information about Augur-related events directly on the Ethereum blockchain, the Simplified API sends query requests to an Augur Node’s database. This is because looking up information directly on the blockchain can be a slow and difficult process, especially when sorting is required. For example, to run a query for all Markets created by a specific user, sorted by volume and limited to 100 results, would require scanning the blockchain for all Market creation events by that user, saving the results locally, querying each Market to obtain its volume, saving those results locally, and then sorting the Markets created by the user and discarding everything after the first 100 results. This would require a large number of RPC requests and would take a long time to complete.

To alleviate this problem, the Simplified API executes queries by submitting an RPC request to an Augur Node that is either running locally or remotely (hosted). The Augur Node then runs the request against its database and returns the result. This allows queries to be run on Augur much more quickly than would otherwise be possible.

It should be noted that batch RPC calls are not supported yet on incoming requests to Augur Node, and therefore batch RPC calls currently are not supported by augur.js.

To set up a local Augur Node, follow the instructions described in the Augur Node GitHub repository. Once a local Augur Node is running (or if the WebSocket address of a hosted node is known), a connection to it can be established by specifying the WebSocket address as shown by the JavaScript sample code in the Getting Started with augur.js section.

Getting Started with augur.js

// After installing, just require augur.js to use it.varAugur=require('augur.js');varaugur=newAugur();varethereumNode={httpAddresses:["http://127.0.0.1:8545",// local HTTP address for Geth node"https://rinkeby.augur.net/ethereum-http"// hosted http address for Geth node on the Rinkeby test network],wsAddresses:["ws://127.0.0.1:8546",// local WebSocket address for Geth node"wss://rinkeby.augur.net/ethereum-ws"// hosted WebSocket address for Geth node on the Rinkeby test network]// ipc addresses can also be specified as:// ipcAddresses: [ ... ]};// To connect to a hosted Augur Node instead of a local Augur Node, substitute its WebSocket address below.varaugurNode="ws://127.0.0.1:9001";// local WebSocket address for an Augur Node// Attempt to connect to a local Ethereum node// If that fails, fall back to the hosted Ethereum nodeaugur.connect({ethereumNode,augurNode},function(err,connectionInfo){/* ... */});// example connectionInfo object:{augurNode:"ws://127.0.0.1:9001",ethereumNode:{contracts:{Controller:"0xb1772d9e581e5a245ff429cca3e06c57d567c58c",Universe:"0xaa88b74da9e08d44c996f037ce13cb2711053cea",Augur:"0xdddc5d40979660308e8017d048b04782f17af4af",OrdersFinder:"0x01f2aba090b5fa26a64ea9e5afd32f6aab6ba3df",LegacyReputationToken:"0x59c98505653f68e8cc2a0ac1e84380a0393fd04e",CancelOrder:"0x4c0f599bdd8f9eac10cdfd152c3110ea9b803088",Cash:"0x5754d0bcb36b7f30999199031d1f323c4079d58d",ClaimTradingProceeds:"0xe408a58ff3eb050f39728fc45644f64e8e379e3d",CompleteSets:"0xb51a3aab3d5009f21cd9b47ae856aa780460b78c",CreateOrder:"0x19ef3d62d49e95e1b92c1fe12986a24a42c4f3c3",FillOrder:"0x57972b23e4e97cf33b456d292411308b1053d835",Order:"0x86416fd9eb6ca7797f799ccc2e08a4da4083ac17",Orders:"0x452cbdba8559a9b0199bb15105a42fc7ae373983",OrdersFetcher:"0xc9d0126e1aa921056af5981016904690ad73c0d3",ShareToken:"0x5c8b3117b65af65405980f3700542c03709a6436",Trade:"0x8d0677ee9f5330fd65db56da6c31711fd6810434",TradingEscapeHatch:"0x867d606553c3fc24b35e3b02d228dc1647786f88"},abi:{events:{/* ... */},functions:{/* ... */}},}}

Once augur.js has been installed, it will need to be connected to an Ethereum node and an Augur node. These can be running locally or remotely (hosted).

To connect to the desired Ethereum node and Augur node, call the function augur.connect as shown to the right. Upon doing so, augur.js will iterate through the list of addresses provided in the ethereumNode argument and attempt to connect to each one until a successful connection is established or all attempts have failed. The Ethereum node may have multiple HTTP, WebSocket, or IPC addresses specified as arrays. The connection will be chosen automatically based on a preference of IPC > WS > HTTP. Note: if there is a global web3 object present, such as that injected by MetaMask, that global web3 will be automatically used in preference to any other connections available. So, if you’re using MetaMask, make sure it’s connected to the right network!

Similarly, augur.js will attempt to use the augurNode parameter to connect to an Augur Node. However, augurNode may only be specified as a single-address string, not as an object containing an array of addresses.

The Augur development team hosts Augur Nodes and Ethereum nodes on the Ethereum test networks. The addresses for these hosted nodes are as follows:

The Augur development team does not host any Augur Nodes or Ethereum nodes for the Ethereum main network. However, a list of these nodes that are hosted by trusted community members can be found at https://predictions.global/augur-public-ethereum-nodes.

In the example on the right, the first connection that will be tried is http://127.0.0.1:8545, which is a local Ethereum node being run using the Geth client. If a connection to the local Geth node cannot be established, the next provided address will be tried. In this case, we have provided a single hosted node on the Ethereum Rinkeby test network (rinkeby.ethereum.nodes.augur.net) as another attempt to make after the local Geth node. If a connection is successfully established, then the vitals object will be returned; otherwise an error message will be returned.

It should be noted that Augur’s back-end Solidity smart contracts are deployed from the perspective of augur.js, which means that augur.js contains a list of Augur’s smart contract addresses in the file augur.js/src/contracts/addresses.json.

The each group of addresses in the file maps to an Ethereum network ID or to the network ID of a local Ethereum node in a Docker image:

1 - Main network

3 - Ropsten test network

4 - Rinkeby test network

19 - Thunder network

42 - Kovan test network

101 - Network ID for a local node (used when running Docker image dev-node-geth in augur.js)

Augur’s smart contract ABIs are generated and output to augur-core/output/contracts/abi.json in the augur-core repository by the script augur-core/source/libraries/ContractCompiler.ts. For further details on Augur’s smart contracts and their compiling/deployment process, please refer to the README file in the augur-core repository.

Numbers

It is strongly recommended that all numerical input values be passed into Call API functions and Transaction API functions as hexadecimal strings. This is because these API functions are direct bindings to the functions on Augur’s smart contracts, and passing in very large numbers in decimal form can result in the functions on Augur’s smart contracts failing.

The Simplified API functions, however, automatically convert numerical input values to hexadecimal form before passing them into Augur’s smart contracts.

For the Simplified API, there are three acceptable ways to pass numerical inputs:

Floating-point (decimal) values should be passed to augur.js as strings (e.g., instead of 0.07, use "0.07"), for reasons described in enormous detail elsewhere.

All numerical parameters passed to augur.js must be either base 10 (decimal) or base 16 (hexadecimal). Do not use the base 1018 fixed-point representation that Augur uses internally for decimals! augur.js handles all fixed-point conversions for you.

Initial Market Loading

To get a list of all Markets, first call augur.markets.getMarkets. More detailed market info (including prices) for each market can then be loaded using augur.markets.getMarketsInfo. augur.markets.getMarketsInfo does not return the Open Orders for the Market; to get the Open Orders, call augur.trading.getOrders.

The function augur.rpc.setDebugOptions allows several debugging options to be enabled:

broadcast - When set to true, this enables printing of verbose, low-level information related to sending/receiving transactions, such as the transaction JSON that gets sent out over the wire, incoming eth_subscription messages, etc.

connect - When set to true, this enables printing of the result of the initial connection of ethrpc to the underlying Ethereum node, as well as which endpoints are connected, on which protocols

tx - When set to true, this enables printing of information related to transaction construction/submission/confirmation. This information includes the intermediate “transaction” object with human-readable parameters, the (best-guess) return value fetched from the follow-up eth_call when a transaction gets resubmitted, and the transaction hash once the transaction is submitted.

Simplified API

The Simplified API provides an easy way to make transactions and query for information within Augur. This API is simplified in the sense that single requests to this API can be used to fetch a large amount of data, without the need for complicated RPC batch queries. However, many of the functions in this API require a connection to an Augur Node, which has been indicated in their descriptions. Please read the Augur Node section before using these functions.

augur.accounts.approveAugur(p)

Internally, Augur uses an ERC-20 token called Cash as a wrapper for ETH. Many of Augur’s transactions require Augur to be able to spend Cash on behalf of the account executing the transaction. However, the account must first approve Augur to spend that amount of Cash on its behalf. This function calls the function augur.api.Cash.approve to approve Augur to spend up to augur.constants.ETERNAL_APPROVAL_VALUE Cash on behalf of the account. augur.constants.ETERNAL_APPROVAL_VALUE is equal to 2^256 - 1, or the maximum amount of Cash that can be approved. This value is used so that augur.api.Cash.approve does not have to be called multiple times in order to execute multiple transactions.

Parameters:

p (Object) Parameters object.

p.address (string) Ethereum address of the account making the approval.

augur.accounts.getAccountTransferHistory(p, callback)

Parameters:

p.account (string) Ethereum address of the account for which to get transfer history, as a 20-byte hexadecimal string.

p.token (string) <optional> Contract address of the token contract by which to limit the history results, as a 20-byte hexadecimal string.

isInternalTransfer (boolean) <optional> When set to true, only trade/order transfers will be returned; otherwise, all transfers for the account are returned. (This is not perfectly accurate, as it is possible for a trade and a non-trade/order-related transfer to appear in the same transaction. This can occur if done via a smart contract, which performs a standard transfer and a trade in the same transaction.) Defaults to false.

p.earliestCreationTime (number) <optional> Earliest timestamp, in seconds, at which to truncate history results. (This timestamp is when the block on the Ethereum blockchain containing the transfer was created.)

p.latestCreationTime (number) <optional> Latest timestamp, in seconds, at which to truncate history results. (This timestamp is when the block on the Ethereum blockchain containing the transfer was created.)

p.sortBy (string) <optional> Field name by which to sort transfer history.

p.isSortDescending (boolean) <optional> Whether to sort transfers in descending order by sortBy field.

p.limit (number) <optional> Maximum number of transfers to return.

p.offset (number) <optional> Number of transfers to truncate from the beginning of the history results.

callback (function) Called after the account transfer history has been retrieved.

NOTE: The account attempting to create the new market must have sufficient REP in order for the market to be created. This is also true when calling eth_estimateGas, which essentially does a trial run of the transaction to determine what the gas cost would be to actually run it.

NOTE: The account attempting to create the new market must have sufficient REP in order for the market to be created. This is also true when calling eth_estimateGas, which essentially does a trial run of the transaction to determine what the gas cost would be to actually run it.

Parameters:

p (Object) Parameters object.

p.universe (string) Universe in which to create this market.

p._endTime (number) Market expiration timestamp, in seconds.

p._feePerEthInWei (string) <optional> Amount of wei per ether settled that goes to the Market Creator, as a base-10 string.

p._denominationToken (string) Ethereum address of the token used as this Market’s currency.

p._minPrice (string) Minimum display (non-normalized) price for this Market, as a base-10 string.

p._maxPrice (string) Maximum display (non-normalized) price for this Market, as a base-10 string.

NOTE: The account attempting to create the new market must have sufficient REP in order for the market to be created. This is also true when calling eth_estimateGas, which essentially does a trial run of the transaction to determine what the gas cost would be to actually run it.

Parameters:

p (Object) Parameters object.

p.universe (string) Universe in which to create a Yes/No Market.

p._endTime (number) Yes/No Market expiration timestamp, in seconds.

p._feePerEthInWei (string) <optional> Amount of wei per ether settled that goes to the Market Creator, as a base-10 string.

p._denominationToken (string) Ethereum address of the token used as this Market’s currency.

Returns:

augur.createMarket.getMarketCreationCostBreakdown(p, callback)

Similar to augur.createMarket.getMarketCreationCost, but provides more detail about the ether costs required to create a new Market. These Ether costs are broken down by the gas cost paid to the First Public Reporter and the cost of the Validity Bond.

Note: This function will send a transaction if needed to create the current Fee Window.

Get Gas Price Function

augur.getGasPrice(newGasPriceFunction)

Returns the current gas price.

Parameters:

newGasPriceFunction (function) Callback function to be used to retrieve the current gas price. By default, ethrpc’sgetGasPrice function will be called, and the result will be passed into this callback function.

augur.markets.getMarkets(p, callback)

Parameters:

p.universe (string) Contract address of the Universe from which to get transfer history.

p.creator (string) <optional> Ethereum address of a Market Creator by which to filter the returned results, as a 20-byte hexadecimal string.

p.category (string) <optional> Market category by which to filter the returned results.

p.search (string) <optional> Query string used to determine which Markets are returned by augur.markets.getMarkets. By default, a full-text search will be performed on this string. However, it is also possible to search across specific market properties, by specifying marketId, category, tags, shortDescription, longDescription, resolutionSource, and scalarDenomination. For example, to search within market categories, p.search can be set to “category: ETH”. More complex queries can be formed using “AND” and “OR”. For example, setting p.search to “category: Ethereum OR tags: ETH” will search for all markets with the category “Ethereum” or the tag “ETH”.

p.reportingState (string|Array<string>) <optional> REPORTING_STATE (or array of REPORTING_STATEs) by which to filter the returned results.

p.feeWindow (string) <optional> Ethereum address of a Fee Window by which to filter the returned results, as a 20-byte hexadecimal string.

p.designatedReporter (string) <optional> Ethereum address of a Designated Reporter by which to filter the returned results, as a 20-byte hexadecimal string.

p.maxFee (number) <optional> Maximum trading Settlement Fee by which to filter the returned results, as a decimal number. (For example, if the desired maximum Settlement Fee is 1.0201%, maxFee should be set to 0.010201.)

p.maxEndTime (number) <optional> Maximum Market end time by which to filter Markets, as a Unix timestamp.

p.maxSpreadPercent (number) <optional> Maximum Spread Percent by which to filter markets, as a decimal number from 0 to 1.

p.hasOrders (boolean) <optional> If set to true, only Markets having Open Orders on the Order Book will be returned. Defaults to false.

p.sortBy (string) <optional> Field name by which to sort the Markets.

p.isSortDescending (boolean) <optional> Whether to sort the Markets in descending order by sortBy field.

p.limit (number) <optional> Maximum number of Markets to return.

p.offset (number) <optional> Number of Markets to truncate from the beginning of the results.

callback (function) Called after the Markets have been retrieved.

Returns:

(Array.<string>) Array of Market addresses in the Universe, as hexadecimal strings.

augur.markets.getMarketsClosingInDateRange(p, callback)

Returns the Markets closing between a given time range in a specific Universe.

Returns:

augur.markets.getMarketsInfo(p, callback)

Returns information about Markets that are stored on-contract. The returned result includes basic information about the Markets as well as information about each Market Outcome. It does not include Order Book information; however the function augur.trading.getOrders can be used to get information about Orders for the specified Market.

augur.reporting.claimReportingFeesForkedMarket(p)

Claims unclaimed Reporting Fees a user has in any InitialReporter/DisputeCrowdsourcer contracts of a specified Forked Market, or returns a gas estimate for claiming these fees if p.estimateGas is true.

The claiming process works as follows:

For each InitialReporter/DisputeCrowdsourcer contract of the Forked Market in which the user has unclaimed fees:

p.redeemed (boolean) <optional> If true, the returned results will include only InitialReporter contracts where the Reporter has redeemed Staked REP; if false, the returned results will include only InitialReporter contracts where the Reporter has not redeemed Staked REP. If not specified, the results will include all InitialReporters in which the Repoter has Staked REP.

p.withRepBalance (boolean) <optional> Whether the InitialReporter contract has a balance greater than 0. If set to true, only InitialReporters with a balance greater than 0 will be returned.

callback (function) Called after the InitialReporters have been retrieved.

augur.reporting.getReportingFees(p, callback)

Parameters:

p.reporter (string) Ethereum address of the Reporter for which to retrieve Reporting Fees, as a 20-byte hexadecimal string.

p.universe (string) Contract address of the Universe in which to look up the Reporting Fees, as a 20-byte hexadecimal string.

Returns:

(GetReportingFeesInfo) information about the unclaimed ETH and REP Reporting Fees a user has in a specific Universe.

augur.reporting.getReportingHistory(p, callback)

Returns information about the Reports submitted by a particular user. For Fee Windows that have ended, this includes the Final Outcome of the Market, whether the user’s Report matched that Final Outcome, how much REP the user gained or lost from redistribution, and how much the user earned in Reporting Fees.

Parameters:

p (Object) Parameters object.

p.reporter (string) Ethereum address of the Reporter for which to retrieve reporting history, as a 20-byte hexadecimal string.

p.universe (string) <optional> Contract address of the Universe in which to look up the reporting history, as a 20-byte hexadecimal string. Either this parameter, the Market ID, or the Fee Window must be specified.

p.marketId (string) <optional> Contract address of the Market in which to look up the reporting history, as a 20-byte hexadecimal string. Either this parameter, the Universe, or the Fee Window must be specified.

p.feeWindow (string) <optional> Contract address of the Fee Window in which to look up the reporting history, as a 20-byte hexadecimal string. Either this parameter, the Universe, or the Market ID must be specified.

p.earliestCreationTime (number) <optional> Earliest timestamp, in seconds, at which to truncate history results. (This timestamp is when the block on the Ethereum blockchain containing the report submission was created.)

p.latestCreationTime (number) <optional> Latest timestamp, in seconds, at which to truncate history results. (This timestamp is when the block on the Ethereum blockchain containing the report submission was created.)

p.sortBy (string) <optional> Field name by which to sort the reporting history.

p.isSortDescending (boolean) <optional> Whether to sort the reporting history in descending order by sortBy field.

p.limit (number) <optional> Maximum number of reporting history reports to return.

p.offset (number) <optional> Number of reporting history reports to truncate from the beginning of the results.

callback (function) Called when reporting history has been received and parsed.

Returns:

(Object) Reporting history, keyed by Universe or Market ID. Each report is of type Report.

augur.reporting.getReportingSummary(p, callback)

Returns the number of Markets in various reporting phases. For a list of all reporting state descriptions, refer to the REPORTING_STATE type definition.

Returns:

(TradeCost) Object containing information about the cost of placing the trade specified by the parameters in p.

augur.trading.claimMarketsTradingProceeds(p)

Similar to the function augur.trading.claimTradingProceeds, but attempts to collect trading profits in Ether from a user’s outstanding Shares in multiple Finalized Markets instead of a single Finalized Market.

Parameters:

p (Object) Parameters object.

p.markets (Array.<string>) Array of Market addresses for which to claim proceeds.

p._shareHolder (string) User address that holds the shares, as a 20-byte hexadecimal string.

Returns:

augur.trading.generateTradeGroupId(tradeGroupIdNumBytes)

Returns a randomly-generated trade group ID. (Trade group IDs are used by Augur’s UI to group orders.)

Parameters:

p (Object) Parameters object.

tradeGroupIdNumBytes (number) <optional> Number of bytes the returned trade group ID should be. Defaults to augur.constants.TRADE_GROUP_ID_NUM_BYTES.

Returns:

(string) Randomly-generated trade group ID.

augur.trading.getBetterWorseOrders(p, callback)

Returns the IDs of the Orders for a given Outcome that have a better and worse price than the specified price. If no better/worse Orders exist, null will be returned. This function should be called prior to calling augur.api.CreateOrder.publicCreateOrder in order to get the _betterOrderId and _worseOrderId parameters that it accepts. (_betterOrderId and _worseOrderId are used to optimize the sorting of Orders on the Order Book.)

p.creator (string) <optional> Ethereum address of the Order creator, as a 20-byte hexadecimal string.

p.orderState (ORDER_STATE) <optional> State of orders by which to filter results. Valid values are “ALL”, “CANCELED”, “CLOSED”, & “OPEN”.

p.orphaned (boolean) <optional> When set to true, this parameter causes the function to return only Orphaned Orders; otherwise, the function returns non-Orphaned Orders. Defaults to false.

p.earliestCreationTime (number) <optional> Earliest timestamp, in seconds, at which to truncate order results. (This timestamp is when the block on the Ethereum blockchain containing the transfer was created.)

p.latestCreationTime (number) <optional> Latest timestamp, in seconds, at which to truncate order results. (This timestamp is when the block on the Ethereum blockchain containing the transfer was created.)

p.sortBy (string) <optional> Field name by which to sort the orders.

p.isSortDescending (boolean) <optional> Whether to sort orders in descending order by sortBy field.

p.limit (number) <optional> Maximum number of orders to return.

p.offset (number) <optional> Number of orders to truncate from the beginning of the results.

callback (function) Called when the requested orders for this Market/Universe have been received and parsed.

Returns:

(Object) Object containing a SingleSideOrderBook object for one side of the Order Book (buy or sell), keyed by Universe/Market and Outcome.

augur.trading.getUserTradingHistory(p, callback)

Parameters:

p.account (string) Ethereum address of the user for which to retrieve trading history, as a 20-byte hexadecimal string.

p.universe (string) <optional> Contract address of the Universe in which to look up the trading history, as a 20-byte hexadecimal string. Either this parameter or the Market ID must be specified.

p.marketId (string|Array<string>) <optional> Contract address(es) of the Market(s) in which to look up the trading history, as a 20-byte hexadecimal string. Either this parameter or the Universe must be specified.

p.outcome (number) Outcome of the Share being bought/sold. Valid values are in the range [0,7].

p.onSent (function) Called when the first trading transaction is broadcast to the network.

p.onSuccess (function) Called when the full trade completes successfully.

p.onFailed (function) Called if any part of the trade fails.

Returns:

This function does not return a value.

augur.trading.simulateTrade(p, callback)

Determines the sequence of makes/takes that will be executed to Fill the specified Order, and returns the user’s projected balances and fees paid after this sequence is completed. Note: This function automatically normalizes Share prices, so “display prices” can be passed in directly for minPrice, maxPrice, and price.

Parameters:

p (Object) Trade simulation parameters.

p.orderType (number) Order type (0 for “buy”, 1 for “sell”).

p.outcome (number) Outcome ID to trade. Valid values are in the range [0,7].

p.shareBalances (string[]) Number of Shares the user owns of each Outcome in ascending order, as an array of base-10 strings.

p.tokenBalance (string) Number of tokens (e.g., wrapped Ether) the user owns, as a base-10 string.

p.shouldCollectReportingFees (boolean) <optional> False if reporting fees are not collected; this is rare and only occurs in disowned Markets. Defaults to true.

Returns:

(SimulatedTrade) Projected fees paid, shares and tokens spent, and final balances after the trade is complete.

augur.trading.tradeUntilAmountIsZero(p, callback)

If p.doNotCreateOrders is set to true, this function will place trades until all Orders equal to or better than the specified price limit are removed from the Order Book.

If p.doNotCreateOrders is set to false, this function will place trades until the user’s request has been fulfilled. This is done by attempting to trade until all Orders equal to or better than the specified limit price are removed from the Order Book and then creating a new Order with whatever amount is remaining in the user’s request.

Parameters:

p (Object) Parameters object.

p._price (string) Normalized limit price for this trade, as a base-10 string.

The Call API of augur.js is made up of “getter” functions that retrieve information from Augur’s Solidity smart contracts using Ethereum’s eth_call RPC; however, these functions do not write any information to the Ethereum blockchain. The Call API is intended for more granular “gets” than the Simplified API allows, and its functions are mapped directly to the public functions of Augur’s Solidity smart contracts.

All functions in the Call API accept two arguments:

p, a parameters object containing any key/value pairs matching the input parameters for the contract method, and (in some cases) a tx object with the Ethereum contract address to call. The tx object is described in more detail in the Transaction API section.

A callback function.

The Call API functions are part of the augur.api object and follow a pattern of augur.api.<Contract Name>.<Contract Function>(<Parameters Object>, <Callback Function>).

Augur’s Call API has been updated to return promises. Passing in a callback still works the same as before; however, now the underlying promise is returned directly to the caller.

Controller Call API

Provides JavaScript bindings for the Controller Solidity Contract, which is used to manage whitelisting of contracts and and halt the normal use of Augur’s contracts (e.g., if there is a vulnerability found in Augur). From a developer standpoint, it can be used to get Augur’s internal timestamp.

augur.api.Controller.getTimestamp(p, callback)

Returns Augur’s internal Unix timestamp.

Parameters:

p (Object) Parameters object.

callback (function) <optional> Called after the function’s result has been retrieved.

augur.api.DisputeCrowdsourcer.getStake(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Dispute Crowdsourcer on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) attoREP Staked on the Dispute Crowdsourcer, as a stringified unsigned integer.

augur.api.DisputeCrowdsourcer.isDisavowed(p, callback)

Returns whether a Dispute Crowdsourcer has been “disavowed”. A disavowed Dispute Crowdsourcer is one from which StakedREP and/or Reporting Fees can be redeemed (by calling augur.api.DisputeCrowdsourcer.redeem) and whose Market has not necessarily been Finalized. A Dispute Crowdsourcer can become disavowed if any of the following occurs:

Another Dispute Crowdsourcer belonging to the same Market and in the same Fee Window successfully fills its Dispute Bond.

A Market other than the Dispute Crowdsourcer’s Market causes a Fork, and augur.api.Market.disavowCrowdsourcers is called on the Dispute Crowdsourcer’s Market.

The Dispute Crowdsourcer’s Market Forks, and augur.api.DisputeCrowdsourcer.fork is called on the Dispute Crowdsourcer.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Dispute Crowdsourcer on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Dispute Crowdsourcer has been disavowed, or false otherwise.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Fee Window on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Number of Markets in the Fee Window, where the Designated Report was Challenged in the current Dispute Round Phase or the Designated Reporter did not Report, as a stringified unsigned integer.

augur.api.FeeWindow.getNumInvalidMarkets(p, callback)

Returns the number of Markets that were Reported to be Invalid during the specified Fee Window. Invalid Markets are Markets that aren’t clearly defined or do not fit one of the Outcomes set for this Market. Reporters are encouraged to Report the Market as Invalid if they can’t confidently Stake their REP into a single Outcome for the Market.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Fee Window on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Number of Markets Reported as Invalid in the Fee Window, as a stringified unsigned integer.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Fee Window on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Reputation Token used by the Fee Window, as a 20-byte hexadecimal string.

augur.api.FeeWindow.getStartTime(p, callback)

Returns a Unix timestamp of when a Fee Window becomes active and starts. A Fee Window is considered active for a total of 7 days, then ends, and is no longer considered to be active. Only active Fee Windows allow Reporters to Challenge the Tentative Outcomes of Markets contained in the Fee Window.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Fee Window on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Unix timestamp at which the Fee Window starts, as a stringified unsigned integer.

augur.api.FeeWindow.getUniverse(p, callback)

Returns the Universe to which the specified Fee Window belongs. Every Fee Window belongs to a specific Universe in which they were created and can operate.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Fee Window on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Universe to which the Fee Window belongs, as a 20-byte hexadecimal string.

augur.api.FeeWindow.isActive(p, callback)

Returns whether the specified Fee Window is currently active. Fee Windows are considered active during the Window’s Dispute Round Phase, which last a total of 7 days.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Fee Window on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

augur.api.InitialReporter.getReputationToken(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the InitialReporter contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Reputation Token Ethereum contract address used by the InitialReporter contract, as a 20-byte hexadecimal string.

augur.api.InitialReporter.getSize(p, callback)

Returns the amount of attoREP required to be Staked on an Outcome in order to submit the Initial Report. For Initial Reports, this value will always be the same as the value returned by augur.api.InitialReporter.getStake.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the InitialReporter contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Amount of attoREP Staked on the Reported Outcome of the Initial Report, as a stringified unsigned integer.

augur.api.InitialReporter.getStake(p, callback)

Returns the amount of attoREPStaked on the ReportedOutcome of the specified InitialReporter contract. For Initial Reports, this value will always be the same as the value returned by augur.api.InitialReporter.getSize.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the InitialReporter contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Amount of attoREP Staked on the Initial Report for the Market of the specified InitialReporter contract, as a stringified unsigned integer.

augur.api.Market.designatedReporterWasCorrect(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Payout Distribution Hash submitted in the Designated Report is the same as the winning Payout Distribution Hash for the specified Market, or false otherwise.

augur.api.Market.getCrowdsourcer(p, callback)

Returns the Ethereum address for the DisputeCrowdsourcer contract that corresponds to the given Payout Distribution Hash.

Note: Calling this function only works for retrieving a DisputeCrowdsourcer if the Dispute Round has not been completed yet.

Parameters:

p (Object) Parameters object.

p._payoutDistributionHash (string) Payout Distribution Hash for the Outcome of the Dispute Crowdsourcer, as a 32-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum address for the DisputeCrowdsourcer contract that corresponds to the given Payout Distribution Hash, as a 20-byte hexadecimal string.

augur.api.Market.getDenominationToken(p, callback)

Returns the Ethereum contract address of the token used to denominate the specified Market. A Denomination Token is the ERC-20 Token used as the currency to trade on the Outcome of a Market. Currently, this function will always return the address of a Cash contract; however, Augur will eventually support other types of Denomination Tokens.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the token used to denominate the specified Market, as a 20-byte hexadecimal string.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Unix timestamp for when the Market was Finalized, as a stringified unsigned integer. If the Market does not have a finalization time yet, “0” will be returned.

augur.api.Market.getForkingMarket(p, callback)

Returns the Ethereum contract address of the Forked Market for the Universe that contains the specified Market address. If the Market address specified belongs in a Universe that hasn’t had a Fork take place, this will return 0x0.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Forked Market for the Universe in which the specified Market exists, as a 20-byte hexadecimal string.

augur.api.Market.getInitialReporter(p, callback)

Returns the Ethereum address of the InitialReporter contract for a given Market.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum address of the Market’s InitialReporter contract, as a 20-byte hexadecimal string.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Number of Ticks for the Market, as a stringified unsigned integer.

augur.api.Market.getParticipantStake(p, callback)

Returns the total amount of attoREP Staked on all Outcomes of the specified Market. This amount is combined total of attoREP Staked on the Initial Report and attoREP Staked on every successful Dispute Crowdsourcer.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Total attoREP Staked on the Market, as a stringified unsigned integer.

augur.api.Market.getReportingParticipant(p, callback)

Within Augur’s code, the InitialReporter class and DisputeCrowdsourcer class are child classes of a class called ReportingParticipant. When an Initial Report is submitted or a Dispute Crowdsourcer fills its Dispute Bond, the corresponding Market pushes that InitialReporter contract or DisputeCrowdsourcer contract to an array that keeps track of all contracts that have ever been the Tentative Outcome. The function augur.api.Market.getReportingParticipant returns the Ethereum address of the contract at a specific index in that array.

Note: To get the address of the ReportingParticipant that is currently winning in a Market, call augur.api.Market.getWinningReportingParticipant.

Parameters:

p (Object) Parameters object.

p._index (string) Index of the ReportingParticipant in the Market’s array of ReportingParticipant contracts, as a hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum address of a ReportingParticipant contract for the Market, as a 20-byte hexadecimal string.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Reputation Token for the Market, as a 20-byte hexadecimal string.

augur.api.Market.getShareToken(p, callback)

Returns the Ethereum contract address of the Share Token for the specified Market and Outcome. Every Outcome of a Market has a separate Share Token used to handle trading around that Outcome and this method returns the contract address of the Share Tokens for the specified Outcome. Share Tokens are used within Augur to represent Shares.

Parameters:

p (Object) Parameters object.

p._outcome (string) Outcome for which to get the Share Token Ethereum contract address, as a hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Share Token for the specified Market and Outcome, as a 20-byte hexadecimal string.

augur.api.Market.getWinningPayoutNumerator(p, callback)

Parameters:

p._outcome (string) Outcome for which to get the winning Payout Numerator, as a hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Winning Payout Numerator for an Outcome in the Market, as a stringified unsigned integer.

augur.api.Market.getWinningReportingParticipant(p, callback)

Within Augur’s code, the InitialReporter class and DisputeCrowdsourcer class are child classes of a class called ReportingParticipant. When an Initial Report is submitted or a Dispute Crowdsourcer fills its Dispute Bond, the corresponding Market pushes that InitialReporter contract or DisputeCrowdsourcer contract to an array that keeps track of all contracts that have ever been the Tentative Outcome. The function augur.api.Market.getWinningReportingParticipant returns the Ethereum address of the ReportingParticipant contract that corresponds to the Market’s Tentative Outcome.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum address of the ReportingParticipant contract corresponding to the Market’s Tentative Outcome, as a 20-byte hexadecimal string.

augur.api.Market.isContainerForReportingParticipant(p, callback)

Returns whether the ReportingParticipant contract _shadyReportingParticipant belongs to the specified Market. (Both the DisputeCrowdsourcer and InitialReporter classes in Augur’s Solidity smart contracts are considered Reporting Participants, since they have the parent class BaseReportingParticipant.)

Parameters:

p (Object) Parameters object.

p._shadyReportingParticipant (string) ReportingParticipant Ethereum contract address for which to check if the Market is a container, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Market is a container for the ReportingParticipant contract, or false otherwise.

augur.api.Market.isContainerForShareToken(p, callback)

Returns whether the given Market is a container for the specified Share Token Ethereum contract address.

Parameters:

p (Object) Parameters object.

p._shadyShareToken (string) ShareToken Ethereum contract address for which to check if the Market is a container, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Market contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Market is a container for the specified Share Token, or false otherwise.

p._bestOrderId (string) Best Order ID on the Order Book for p._type, as a 32-byte hexadecimal string.

p._worstOrderId (string) Worst Order ID on the Order Book for p._type, as a 32-byte hexadecimal string.

p._betterOrderId (string) Order ID with a better price than p._price, as a 32-byte-hexadecimal string.

p._worseOrderId (string) Order ID with a worse price than p._price, as a 32-byte-hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(Array.<string>) Array containing the better Order ID and worse Order ID, respectively, for the specified price and Order type.

Orders Finder Call API

// Orders Finder Contract Call API Examples:// All OrdersFinder functions can be called like the example below, but return different array lengths.varordersFinder="0xf28fc4b34a7c4534dd3e40e0ad5df6f2cb69aec0";augur.api.OrdersFinder.getExistingOrders5({_type:"0x1",_market:"0xd8e090ac1282fd54d4f7ff5474f6e363cf30049e",_outcome:"0x1",tx:{to:ordersFinder}},function(error,feeWindow){console.log(feeWindow);});["0xfa76427aaada4f319a831f6b2579557ee30579dac997cbe6d7737b438a788a2b","0xf77843d1520fe797874779a2447cd8727a3ff985975cbe2e0f660e6aa27fff8f","0x38e6d59a9d4953dbdda92de3561c044b86640236ed8398666155a031bfd77e69","0x1673d59a9d497384dda92de3561c044b86640236ed8398666155a031bfd89263","0x8245959a9d4953dbdda92de3561c044b86640236ed8398666155a031bfd09837"]

The Reputation Token, or REP, is an ERC-20 token that implements all of the required functions listed in the ERC-20 Token Standard. It does not, however, implement the optional functions.

augur.api.ReputationToken.allowance(p, callback)

Returns the amount of attoREP that a given Ethereum contract is allowed to spend on behalf of a particular user.

Parameters:

p (Object) Parameters object.

p._owner (string) Ethereum address of the owner of the REP, as a 20-byte hexadecimal value.

p._spender (string) Ethereum address of the contract allowed to spend on behalf of p._owner, as a 20-byte hexadecimal string. (This should be the address of the Augur.sol contract.)

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the ReputationToken contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Amount of attoREP the contract is allowed to spend on behalf of the specified user.

augur.api.ReputationToken.getUniverse(p, callback)

Returns the Ethereum contract address of the Universe in which the REP of the ReputationToken contract can be used.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the ReputationToken contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Universe in which the REP of the ReputationToken contract can be used, as a 20-byte hexadecimal string.

augur.api.ReputationToken.getTotalMigrated(p, callback)

Returns total amount of REP that has been migrated into the current ReputationToken contract from the ReputationToken contract of its Universe’sParent Universe.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the ReputationToken contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Total amount of REP that has been migrated into the current ReputationToken contract from the ReputationToken contract of its Universe’s Parent Universe, as a stringified unsigned integer.

augur.api.ReputationToken.getTotalTheoreticalSupply(p, callback)

Returns the total Theoretical REP Supply for this ReputationToken contract. Note: To ensure this number is as accurate as possible, augur.api.ReputationToken.updateParentTotalTheoreticalSupply should first be called on the ReputationToken contract, and augur.api.ReputationToken.updateSiblingMigrationTotal should be called on any ReputationToken contracts that have the same Parent Universe.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the ReputationToken contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Total Theoretical REP Supply for this ReputationToken contract, as a stringified unsigned integer.

The Share Token is an ERC-20 token that implements all of the required functions listed in the ERC-20 Token Standard. It does not, however, implement the optional functions. Within Augur, it represents Shares in MarketOutcomes.

augur.api.ShareToken.allowance(p, callback)

Returns the amount of Share Units that a given Ethereum contract is allowed to spend on behalf of a particular user.

Parameters:

p (Object) Parameters object.

p._owner (string) Ethereum address of the owner of the Shares, as a 20-byte hexadecimal value.

p._spender (string) Ethereum address of the contract allowed to spend on behalf of p._owner, as a 20-byte hexadecimal string. (This should be the address of the Augur.sol contract.)

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Amount of Share Units the contract is allowed to spend on behalf of the specified user.

augur.api.ShareToken.getMarket(p, callback)

Returns the Ethereum contract address of the Market for the specified ShareToken.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the ShareToken contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Returns the Ethereum contract address of the Market for the specified ShareToken, as a 20-byte hexadecimal string.

augur.api.ShareToken.getOutcome(p, callback)

Returns the Outcome of the Market that the specified ShareToken is for.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the ShareToken contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Returns the Outcome of the Market that the specified ShareToken is for, as a stringified unsigned integer.

augur.api.Universe.getChildUniverse(p, callback)

Parameters:

p._parentPayoutDistributionHash (string) Payout Distribution Hash for Final Outcome of the desired Child Universe, as a 32-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Universe’s Child Universe that has its Final Outcome set to the specified Payout Distribution Hash, as a 20-byte hexadecimal string. If no such Child Universe exists, the address “0x0000000000000000000000000000000000000000” will be returned.

augur.api.Universe.getCurrentFeeWindow(p, callback)

Returns the Ethereum contract address of the current running Fee Window of a Universe. Every Universe has a Fee Window that runs for a duration of 7 days before immediately starting the next Window.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the current running Fee Window of the Universe, as a 20-byte hexadecimal string.

augur.api.Universe.getFeeWindow(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the given Fee Window in the Universe, as a 20-byte hexadecimal string. If a Fee Window with the specified ID does not exist, the address “0x0000000000000000000000000000000000000000” will be returned.

augur.api.Universe.getFeeWindowByTimestamp(p, callback)

Returns the Ethereum contract address of the Fee Window running at a given timestamp in the Universe.

Parameters:

p (Object) Parameters object.

p._timestamp (string) Unix timestamp for which to get the corresponding Fee Window, as a hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Fee Window running in the Universe at the specified timestamp, as a 20-byte hexadecimal string. If a Fee Window with the specified timestamp does not exist, the address “0x0000000000000000000000000000000000000000” will be returned.

augur.api.Universe.getFeeWindowId(p, callback)

Returns the Fee Window ID for the Universe at the specified timestamp. This ID is calculated by dividing the timestamp by the Universe’s Fee Window duration in seconds.

Parameters:

p (Object) Parameters object.

p._timestamp (string) Unix timestamp for which to get the corresponding Fee Window, as a hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) ID of the Fee Window running the the Universe at the specified timestamp, as a stringified unsigned integer. If the Fee Window contract does not currently exist, “0” will be returned.

augur.api.Universe.getForkEndTime(p, callback)

Returns the Unix timestamp for when the Fork Phase ends that was started on the specified Universe.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Unix timestamp when the Fork Phase ends that was started on the specified Universe, as a stringified unsigned integer. If a Fork has not occurred in the Universe, “0” will be returned.

augur.api.Universe.getForkingMarket(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Market that the specified Universe is Forking over, as a 20-byte hexadecimal string. If the Universe does not contain a Forked Market, the address “0x0000000000000000000000000000000000000000” will be returned.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Estimated amount of attoREP that must be migrated to one Child Universe in order to allow a Fork in the specified Universe to be Finalized before the end of the Fork Phase, as a stringified unsigned integer.

augur.api.Universe.getNextFeeWindow(p, callback)

Returns the Ethereum contract address of the Fee Window coming up after the current Fee Window ends in the specified Universe.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Fee Window coming up after the current Fee Window ends in the specified Universe, as a 20-byte hexadecimal string. If the Fee Window contract for the next Fee Window does not exist yet, the address “0x0000000000000000000000000000000000000000” will be returned.

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Payout Distribution Hash of the Universe’s Parent Universe, as a 32-byte hexadecimal string. If the Universe does not have a Parent Universe (that is, it is a Genesis Universe), the string “0x0000000000000000000000000000000000000000000000000000000000000000” will be returned.

augur.api.Universe.getParentUniverse(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Parent Universe for the specified Universe. If the Universe does not have a Parent Universe (that is, it is a Genesis Universe), the address “0x0000000000000000000000000000000000000000” will be returned.

augur.api.Universe.getPreviousFeeWindow(p, callback)

Returns the Ethereum contract address of the previous Fee Window for the specified Universe.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the previous Fee Window for the specified Universe, as a 20-byte hexadecimal string. If the Fee Window contract for the previous Fee Window does not exist yet, the address “0x0000000000000000000000000000000000000000” will be returned.

augur.api.Universe.getRepMarketCapInAttoeth(p, callback)

Returns an estimate for the REP market cap of the specified Universe. This estimate is updated manually by the Augur development team, roughly once every Fee Window. It is used by Augur to set the price of the Reporting Fee.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

augur.api.Universe.getWinningChildUniverse(p, callback)

Parameters:

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(string) Ethereum contract address of the Winning Universe for a Universe that has Forked, as a 20-byte hexadecimal string.

augur.api.Universe.isContainerForFeeToken(p, callback)

Returns whether the given Universe is a container for a particular Fee Token. Every Fee Token belongs to a Universe, and this method is used to see if a specific Fee Token address belongs to the Universe in question.

This call will fail if:

The Universe is not a container for the Fee Window of the Fee Token.

Parameters:

p (Object) Parameters object.

p._shadyFeeToken (string) Ethereum contract address of the Fee Token for which to check if it belongs to the Universe, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Fee Token belongs to the Universe, or false otherwise.

augur.api.Universe.isContainerForFeeWindow(p, callback)

Returns whether the given Universe is a container for a particular Fee Window. Every Fee Window belongs to a Universe, and this method is used to see if a specific Fee Window address belongs to the Universe in question.

Parameters:

p (Object) Parameters object.

p._shadyFeeWindow (string) Ethereum contract address of the Fee Window for which to check if it belongs to the Universe, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Fee Window belongs to the Universe, or false otherwise.

augur.api.Universe.isContainerForMarket(p, callback)

Returns whether the specific universe is a container for the Market_shadyMarket Ethereum address. All Markets are created within a Universe, and this function is used to confirm if a Market exists within the Universe in question.

Parameters:

p (Object) Parameters object.

p._shadyMarket (string) Ethereum contract address of the Market for which to check if it belongs to the Universe, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Market belongs to the Universe, or false otherwise.

augur.api.Universe.isContainerForReportingParticipant(p, callback)

Returns whether the specified Universe is a container for a particular Reporting Participant. Both the DisputeCrowdsourcers and InitialReporter classes in Augur’s Solidity smart contracts are considered Reporting Participants, since they have the parent class BaseReportingParticipant.

Parameters:

p (Object) Parameters object.

p._shadyReportingParticipant (string) Ethereum contract address of the Reporting Participant for which to check if it belongs to the Universe, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Reporting Participant belongs to the Universe, or false otherwise.

augur.api.Universe.isContainerForShareToken(p, callback)

Returns whether the specific Universe is a container for a given Share Token. (Shares are represented within Augur’s smart contracts as ERC-20 tokens called Share Tokens.)

Parameters:

p (Object) Parameters object.

p._shadyShareToken (string) Ethereum contract address of the Share Token for which to check if it belongs to the Universe, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the Share Token belongs to the Universe, or false otherwise.

augur.api.Universe.isParentOf(p, callback)

Parameters:

p._shadyChild (string) Ethereum contract address of the Universe for which to check if it is a Child Universe of the Universe, as a 20-byte hexadecimal string.

p.tx (Object) Object containing details about how this function call should be made.

p.tx.to (string) Ethereum contract address of the Universe contract on which to call this function, as a 20-byte hexadecimal string.

callback (function) <optional> Called after the function’s result has been retrieved.

Returns:

(boolean) true if the specified Universe is a Child Universe, or false otherwise.

Transaction API

// Transaction API example:// Internally, Augur uses an ERC-20 token called Cash as a wrapper for ETH. // Many of Augur's transactions require the Augur.sol contract to be able // to spend Cash on behalf of the account executing the transaction. // However, the account must first approve Augur to spend that amount of // Cash on its behalf by calling `augur.api.Cash.approve`.// The Ethereum contract addresses for Augur.sol and Cash.sol // can be obtained by calling `augur.augurNode.getSyncData`.var_augurContractAddress="0x67cbf60a24ab922af99e6f335c0ff2b084d5bdbe";varcashContractAddress="0xec28e64edbce62bde48a14b04f0b557b974a22a9";// Amount of Cash (in attotokens) to approve the Augur.sol contract to // spend on this Ethereum account's behalf.// This example approves the maximum amount, which is // augur.constants.ETERNAL_APPROVAL_VALUE, or 2^256 - 1.var_attoCashTokens=augur.constants.ETERNAL_APPROVAL_VALUE;// The Augur API is organized by Contract and then Method like so:// augur.api.<Contract>.<Method>(<argument object>);augur.api.Cash.approve({_spender:_augurContractAddress,_value:_attoCashTokens,tx:{to:cashContractAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});// example onSent output:{callReturn:null,hash:'0x3cd4a2eb35cc0cd3449c252737255863e60aa521d757d615cefbf280b54313fb'}// example onSuccess output:{blockHash:"0xb1379380e458710f25fea54ae03358832076eadc17825edef482efca3c43a9de",blockNumber:1707928,callReturn:null,from:"0x8fa56abe36d8dc76cf85fecb6a3026733e0a12ac",gas:"0x632ea0",gasFees:"0.000206912",gasPrice:"0xee6b2800",hash:"0x3cd4a2eb35cc0cd3449c252737255863e60aa521d757d615cefbf280b54313fb",input:"0x095ea7b300000000000000000000000067cbf60a24ab922af99e6f335c0ff2b084d5bdbeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",nonce:"0x97",r:"0x804b2a14352d3fa9844c296eb8b9a6b8fed45ca5d56550d1eb558c6571abbaf4",s:"0x3793c21fd315e14950b48a2200e8368ca0d25a2b6291eca9b5bb19753026859f",timestamp:1517688651,to:"0xec28e64edbce62bde48a14b04f0b557b974a22a9",transactionIndex:"0x1",v:"0x2b",value:"0x0"}// example onFailed output:{error:'0x',message:'no response or bad input'}

Augur’s Transaction API (“Tx API” for short) is made up of “setter” methods that can both read from and write to the blockchain using Ethereum’s eth_sendTransaction RPC. Under the hood, the API uses augur.js’s convenience wrapper for eth_sendTransaction which can be accessed using augur.rpc.transact. Although it is possible to call augur.rpc.transact directly (which is discussed in greater detail below), it is generally better and easier to use the built-in API functions. The API functions are attached to the augur.api object and follow a pattern of augur.api.<Contract>.<Method>(<Argument Object>). The API method name, as well as its parameters as keys in the params object, are generally identical to those of the underlying smart contract method.

Arguments

All Transaction API methods accept a single object argument, containing the following:

All required parameters for the smart contract function as key/value pairs.

A tx object (sometimes referred to as the payload object), which contains details about how the transaction should be made.

A meta object, which contains information for signing the transaction.

onSent, onSuccess, and onFailed callback functions.

The tx Object

The tx object must contain a to property, which is the Ethereum address of the contract containing the transaction function, as a 20-byte hexadecimal string. This allows augur.js to know which contract to run the transaction on. A gas property can also be specified for Transaction API functions (though this should not be specified for Call API functions). The gas property represents the gas limit to use when executing the transaction. The gasPrice property represents the gas price (in attoETH, or wei) to use. For Transaction API functions that have the payable modifier in Augur’s Solidity smart contracts, a value property must also be specified, which is the amount of attoETH to send to the function. Some of the Transaction API functions can either be made as a call (which will return a cached value and not use gas) or as a transaction (which will calculate the value and use gas to do so). By default, augur.js will call these functions as transactions, but they can be made as calls instead by specifying the send property as false.

The meta Object

All Transaction API functions accept a meta object as a parameter in order to sign the transaction. The meta object contains a signer property, which should be set to the private key buffer or a signing function, provided by a hardware wallet, of the account that wishes to initiate the transaction. (When logged in using an Edge account, the private key buffer can be obtained by outputting the value state.loginAccount.meta.signer.) The meta object also contains an accountType property, which should be set to “privateKey”, “ledger”, “trezor”, “edge”, or “unlockedEthereumNode”. The Transaction API functions attempt to modify information on the blockchain, which requires the transaction to be signed. The meta parameter is not required when calling Transaction API functions while using MetaMask (which will pop up a separate window asking to confirm the transaction).

Callbacks

Whereas the callback function parameter used by Call API is optional, but strongly recommended, the three callback function parameters used by the Transaction API functions are required. The following keys are used for each callback:

onSent(sentResponse)

Fires when the initial eth_sendTransaction response is received. If the transaction was broadcast to the network without problems, sentResponse will have two fields: txHash (the transaction hash as a hex string) and callReturn (the value returned by the invoked contract method). The optional returns field in the tx object sent to augur.rpc.transact can be used to specify the format of the callReturn value.

onSuccess(successResponse)

Fires when the transaction is successfully incorporated into a block and added to the blockchain, as indicated by a nonzero blockHash value. successResponse is structured the same way as eth_getTransactionByHash responses (see code example for details), with the addition of a callReturn field which contains the contract function’s return value.

onFailed(failedResponse)

Fires if the transaction is unsuccessful. failedResponse has error (error code) and message (error description) fields, describing the way in which the transaction failed.

Approving Augur’s ERC-20 Tokens

Developers will need to grant the Augur.sol contract approval to spend Cash (which is an ERC-20 wrapper for ETH) before many of the Transaction API functions can be called. This can be done by calling the augur.api.Cash.approve function, as shown to the right. Attempting to call many of Augur’s Transaction API functions without doing this first will result in these transactions failing.

Transaction Return Values

It is important to note that Ethereum nodes discard all transaction return values, which causes the callReturn property of the object passed into a transaction’s onSuccess callback to always be null. As a result, there is no way to get a transaction’s return value.

There is, however, a workaround for this issue when calling functions that create Markets, such as augur.api.Universe.createYesNoMarket, augur.api.Universe.createCategoricalMarket, and augur.api.Universe.createScalarMarket. The function augur.createMarket.getMarketFromCreateMarketReceipt can be called in the onSuccess callback of these functions to retrieve the Ethereum contract address of the newly-created Market. augur.createMarket.getMarketFromCreateMarketReceipt does this by querying the Augur Node for the event log associated with the new Market’s creation.

Augur’s Transaction API has been updated to return promises. Passing in callbacks still works the same as before; however, now the underlying promise is returned directly to the caller for `onSuccess` and `onFailed`. (`onSent` is still a callback.)

Using Transact Directly

// Example using `augur.rpc.transact` directly// `tx` object (generated by transfer method of the ReputationToken contract):vartx={constant:false,from:"0x40485264986740c8fb3d11e814bd94cf86012d29",name:"getOrCacheMarketCreationCost",params:[],returns:"uint256",send:true,to:"0x6eabb9367012c0a84473e1e6d7a7ce39a54d77bb"};// privateKeyorSigner is either the privateKey buffer of the account trying to send the transaction or a function to sign a transaction (generally from a hardware wallet). This example uses the Buffer returned from the `augur.accounts.login` function.varprivateKeyOrSigner=[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25];// accountType is a string set to "privateKey", "ledger", "trezor", "edge", or "unlockedEthereumNode".varaccountType="privateKey";// onSent callback fires when the initial eth_sendTransaction response is receivedvaronSent=function(sentResponse){console.log("Transaction sent: ",sentResponse);};// onSuccess callback firesvaronSuccess=function(successResponse){console.log("Transaction successful: ",successResponse);};// onFailed callback fires when the transaction is malformed, fails to confirm,// or an object with an error field is receivedvaronFailed=function(failedResponse){console.error("Transaction failed: ",failedResponse);};augur.rpc.transact(tx,privateKeyOrSigner,accountType,onSent,onSuccess,onFailed);// example onSent output:Transactionsent:{callReturn:null,hash:"0x269011fe4ed9c7370f8e8237c525062988e8fcce485d93a1a6a419bb3a8e70d3"}// example onSuccess output:Transactionsuccessful:{blockHash:"0x5090c1a25a2accf4cb47a1d99f4fa4215146ac29402688ad3e554169af332e4c",blockNumber:1348278,callReturn:null,from:"0x40485264986740c8fb3d11e814bd94cf86012d29",gas:"0x2fd618",gasFees:"0.001882121837379",gasPrice:"0x5b793ccec",hash:"0x0f8e4cdf3de1aa3c01bea8b12cbde32b2bc7701d2bc1b6403634cdd5999ad729",input:"0xec86fdbd",nonce:"0x12",r:"0x3bedf73900da86c9afb6721e472a268108c66694a589b3083935a3c3cc0cc764",s:"0x2c9c24f3bbdd63ba2218de2eddb120f52e966d36fa82989ef6b1e3df0b205ce2",timestamp:1512278406,to:"0x6eabb9367012c0a84473e1e6d7a7ce39a54d77bb",transactionIndex:"0x1",v:"0x2c",value:"0x0"}//example onFailed output:Transactionfailed:{error:501,message:'polled network but could not confirm transaction'}

While it is possible to use augur.rpc.transact directly, it is generally easier and less error-prone to use one of the named API functions documented in the following sections. Readers who want to use the Transaction API and aren’t terribly curious about the augur.js/ethrpc plumbing under the hood should skip to the next section!

Transactions can be broadcast to the Ethereum Network by calling augur.rpc.transact directly. When calling this function directly, the payload object (also known as the tx object) must be constructed carefully as follows:

The signature and params fields are required if the transaction function being called accepts parameters; otherwise, these fields can be excluded. The returns field is used only to format the output, and does not affect the actual RPC request.

The privateKeyOrSigner is required when attempting to execute a transaction that will modify the blockchain (eth_sendTransaction). If the function is simply getting information (eth_call) privateKeyOrSigner can be null. Otherwise, privateKeyOrSigner should be the Private Key Buffer for the logged-in account or a function to sign transactions provided by a hardware wallet.

The accountType is a string that can be “privateKey”, “ledger”, “trezor”, “edge”, or “unlockedEthereumNode”, depending on the type of account that is sending the transaction.

Under the hood, augur.rpc.transact carries out the following sequence:

augur.rpc.transact first attempts to use eth_call on the transaction submitted in order to determine if there is enough gas to perform the transaction and that the transaction is properly formed. If the transaction is malformed, does not provide enough gas, or will fail, an error is passed to the onFailed handler, and the augur.rpc.transact sequence terminates.

After confirming that the Transaction is valid, augur.rpc.transact sends an eth_sendTransaction RPC request (or eth_sendRawTransaction for transactions which are already signed), which broadcasts the transaction to the Ethereum Network. If no transaction hash is received or there is an error, the error is passed to the onFailed handler, and the augur.rpc.transact sequence terminates. Otherwise, the onSent handler is called and returns an object containing the txHash and callReturn.

After calling the onSent handler, Augur adds the transaction to the transactions object (which is indexed by transaction hash, e.g. transactions[txHash]) and assigns the transaction a status of "pending". The function augur.rpc.getTransactions can be used to access the transactions object.

Augur then uses eth_getTransactionByHash to determine if the transaction has been mined or not, indicated by a null response. A null response means that the transaction has been (silently) removed from Geth’s transaction pool. This can happen if the transaction is a duplicate of another transaction that has not yet cleared the transaction pool (and therefore Geth does not fire a duplicate transaction error), or if the transaction’s nonce (but not its other fields) is a duplicate. If a null response is received from eth_getTransactionByHash, Augur will attempt to re-submit the transaction to augur.rpc.transact as long as the number of attempts has not exceeded augur.constants.TX_RETRY_MAX. Once the number of attempts exceeds this threshold, a TRANSACTION_RETRY_MAX_EXCEEDED error is sent to the onFailed handler, and the augur.rpc.transact sequence will terminate.

Once the transaction has been successfully mined (eth_getTransactionByHash successfully returns the transaction object) the transaction is updated to include the blockNumber and blockHash and its status is changed to "sealed".

When the number of confirmations of the transaction exceeds augur.constants.REQUIRED_CONFIRMATIONS, the transaction’s status is updated to "confirmed". A callReturn field is added to the transaction object, which is then passed to the onSuccess handler, completing the sequence.

The augur.rpc object is simply an instance of ethrpc that has its state synchronized with the augur object.

augur.api.Augur.createGenesisUniverse(p)

Allows the caller to create a new Genesis Universe. Users may wish to create a new Genesis Universe if, for example, they would like to create a separate Universe to compete with an existing Universe. Whenever a new Genesis Universe is created, it does not initially contain any Markets or REP supply. In order to add a supply of REP, users must migrate their Legacy REP from the Legacy REP smart contract into the Reputation Token smart contract of the new Genesis Universe using the function augur.api.ReputationToken.migrateFromLegacyReputationToken.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

Returns:

Cash Tx API

// Cash Transaction API Examples:// The Ethereum contract address for Augur.sol can be // obtained by calling `augur.augurNode.getSyncData`.var_augurContractAddress="0x67cbf60a24ab922af99e6f335c0ff2b084d5bdbe";// The Ethereum address of Augur's Cash contract can be // obtained by calling `augur.augurNode.getSyncData`.varcashContractAddress="0xec28e64edbce62bde48a14b04f0b557b974a22a9";// Amount of Cash (in attoCash) to approve the Augur.sol // contract to spend on this Ethereum account's behalf.// This example approves the maximum amount, which is // augur.constants.ETERNAL_APPROVAL_VALUE, or 2^256 - 1.var_attoCash=augur.constants.ETERNAL_APPROVAL_VALUE;augur.api.Cash.approve({_spender:_augurContractAddress,_value:_attoCash,tx:{to:cashContractAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});augur.api.Cash.decreaseApproval({_spender:_augurContractAddress,_subtractedValue:"0x3e8",tx:{to:cashContractAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});augur.api.Cash.increaseApproval({_spender:"",_addedValue:"0x3e8",tx:{to:cashContractAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});augur.api.Cash.withdrawEtherToIfPossible({_to:"0x555e64edbce62bde48a14b04f0b557b974a25555",_amount:"0x3e8",tx:{to:cashContractAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});

Provides JavaScript bindings for the Cash Solidity Contract, which is used internally by Augur as an ERC-20 wrapper for ETH.

augur.api.Cash.approve(p)

Many of the transaction functions in Augur’s smart contracts will only work if the Augur.sol contract has been approved to spend Cash on behalf of the account executing the transaction. This function allows p._spender to spend up to p._value Cash for the msg.sender of this transaction. This transaction will trigger an Approval event, which will record the owner address (msg.sender), p._spender, and p._value in attoCash approved. The amount that p.spender is approved to spend can be increased or decreased later by calling augur.api.Cash.increaseApproval or augur.api.Cash.decreaseApproval.

Parameters:

p (Object) Parameters object.

p._spender (string) Ethereum address of the desired spender, as a 20-byte hexadecimal value.

p._value (string) Number of attoCash to allow p._spender to spend on behalf of msg.sender, as a hexadecimal string.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.send (boolean) <optional> Whether this function should be executed as a transaction. When set to true, this function will be executed as a transaction, which will calculate the value (and thus uses gas). When set to false, this function will be executed as a call, which will return the Reporting Fee amount and will not use any gas.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

Returns:

(null|string) Return value cannot be obtained when executed as a transaction because Ethereum nodes discard transaction return values. However, if p.tx.send is set to false, this function will be executed as a call and will return the Reporting Fee amount, in attoETH, as a stringified unsigned integer.

augur.api.CompleteSets.publicBuyCompleteSets(p)

msg.sender doesn’t have enough of p._market’s denomination token to be able to afford p._amount Shares in all Outcomes.

p._amount is not a number between 1 and 2254.

When successful, this transaction will trigger a CompleteSetsPurchased event, which will record to the Ethereum blockchain msg.sender, p._market, the Universe in which p._market exists, and p._amount purchased.

Parameters:

p (Object) Parameters object.

p._market (string) Ethereum address of the Market in which to buy Complete Sets, as a 20-byte hexadecimal value.

p._amount (string) Number of Share Units to purchase of each Outcome, as a hexadecimal string.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

Returns:

augur.api.CompleteSets.publicBuyCompleteSetsWithCash(p)

This function is not fully implemented yet, but is a intended to be a point-of-contact that would work similarly to augur.api.CompleteSets.publicBuyCompleteSets and allow for a 0x-style trading system.

Parameters:

p (Object) Parameters object.

p._market (string) Ethereum address of the Market in which to buy Complete Sets, as a 20-byte hexadecimal value.

p._amount (string) Number of Share Units to purchase of each Outcome, as a hexadecimal string.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

Returns:

augur.api.CompleteSets.publicSellCompleteSetsWithCash(p)

This function is not fully implemented yet, but is a intended to be a point-of-contact that would work similarly to augur.api.CompleteSets.publicSellCompleteSets and allow for a 0x-style trading system.

Parameters:

p (Object) Parameters object.

p._market (string) Ethereum address of the Market in which to sell Complete Sets, as a 20-byte hexadecimal value.

p._amount (string) Number of Share Units to sell of each Outcome, as a hexadecimal string.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

Returns:

Create Order Tx API

// Create Order Transaction API Examples:// The Ethereum address of Augur's default CreateOrder contract// can be obtained by calling `augur.augurNode.getSyncData`.varcreateOrderAddress="0xdadc071ecc3b7e97b139d2ef692defdc398c8211";// The _betterOrderId/_worseOrderId to use when creating an Order // can be obtained by calling `augur.trading.getBetterWorseOrders`. // In the example below, `augur.trading.getBetterWorseOrders` returnedvar_betterOrderId="0x12328a31378e925ea122ea73e8c81baaf5c731d408487f6884d2e4c81baa3456";var_worseOrderId="0x91c28a31378e925ea122ea73e8c81baaf5c731d408487f6884d2e4c81baa39dd";augur.api.CreateOrder.publicCreateOrder({_type:"0x0",_attoshares:"0x5af3107a4000",_displayPrice:"0x64",_market:"0xc4ba20cbafe3a3655a2f2e4df4ac7f942a722017",_outcome:"0x0",_betterOrderId:_betterOrderId,_worseOrderId:_worseOrderId,_tradeGroupId:"0x0000000000000000000000000000000000000000000000000000000000000000",tx:{to:createOrderAddress,value:"0x470de4df820000",},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});

augur.api.CreateOrder.publicCreateOrder(p)

Creates a new Bid Order or Ask Order on the Order Book. The parameters p._betterOrderId and p._worseOrderId are the Orders with the next best/next worse price after p._displayPrice, and they are used to optimize the process of sorting the new Order on the Order Book. Their IDs can be obtained by calling augur.trading.getBetterWorseOrders. This transaction will trigger an OrderCreated event if the Order is created without any errors.

This transaction will fail if:

p._type is not a valid value of 0 or 1.

p._attoshares is less than 0.

p._market is undefined.

p._outcome is less than 0 or greater than the total number of Outcomes for p._market.

Parameters:

p._type (string) Type of Order to create, as a hexadecimal string (“0x0” for a Bid Order, “0x1” for an Ask Order).

p._attoshares (string) Number of Share Units to buy or sell, as a hexadecimal string.

p._displayPrice (string) Desired price at which to purchase Shares, in attoETH.

p._market (string) Market contract address in which to place the Order, as a 20-byte hexadecimal value.

p._outcome (string) Outcome for which to place the Order, as a hexadecimal string.

p._betterOrderId (string) Order ID of an existing Order on the Order Book with the next-best price with respect to the Order this transaction is intending to create, as a 32-byte hexadecimal value. The Order ID for p._betterOrderId can be obtained by calling augur.trading.getBetterWorseOrders.

p._worseOrderId (string) Order ID of an existing Order on the Order Book with the next-worse price with respect to the Order this transaction is intending to create, as a 32-byte hexadecimal value. The Order ID for p._worseOrderId can be obtained by calling augur.trading.getBetterWorseOrders.

p._tradeGroupId (string) <optional> ID used by the Augur UI to group transactions, as a 32-byte hexadecimal value.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.value (string) Number of attoETH required to create the Order, as a hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

augur.api.DisputeCrowdsourcer.forkAndRedeem(p)

Causes a Child Universe to be created for the Outcome of the Dispute Crowdsourcer and migrates the REP in the Crowdsourcer to the Child Universe. This function can be called only on the Crowdsourcers of a Forked Market, and it can be called at any time after the Fork has begun (including after the Market has been Finalized). When called by a user who Staked on the Dispute Crowdsourcer’s Outcome, it will redeem their Staked REP and collect any Reporting Fees (in Ether) that they are owed.

Returns:

augur.api.DisputeCrowdsourcer.redeem(p)

Redeems REP that p._redeemerStaked on a particular Dispute Crowdsourcer, as well as any Reporting Fees (in Ether) that p._redeemer is owed.

If the Dispute Crowdsourcer’s Market has been Finalized, and the Dispute Crowdsourcer filled its Dispute Bond, the user will receive their Reporting Fees for the Fee Window plus 1.5 times the amount of REP they Staked (if the Outcome of the Dispute Crowdsourcer is the Final Outcome of the Market), or the user will just receive Reporting Fees for the Fee Window (if the Outcome of the Dispute Crowdsourcer is not the Final Outcome of the Market).

If the Dispute Crowdsourcer’s Market has been Finalized, and the Dispute Crowdsourcer did not fill its Dispute Bond, the user will receive Reporting Fees for the Fee Window (but not the REP they originally Staked).

When redeem is called on Dispute Crowdsourcers of non-Forked Markets, this transaction will redeem any REP that p._redeemerStaked on that Crowdsourcer, as well as any Reporting Fees (in Ether) that p._redeemer is owed, to the Universe containing the Forked Market.

When redeem is called on Dispute Crowdsourcers of a Forked Market, it will redeem any REP that p._redeemer Staked on that Crowdsourcer, as well as any Reporting Fees (in Ether) that p._redeemer is owed, to the Child Universe for the Outcome of that Crowdsourcer.

Returns:

augur.api.DisputeCrowdsourcer.withdrawInEmergency(p)

If a critical bug or vulnerability is found in Augur, the Augur development team can put Augur into a halted state until the issue is resolved. In such instances, most regularly-used functions in Augur’s backend will become unuseable until the system is returned to its normal state. When this happens, users can call the withdrawInEmergency function to withdraw the REP they Staked on the Dispute Crowdsourcer’sOutcome. Calling this function will not redeem any Reporting Fees because the total amount of Reporting Fees is not known until the end of the Fee Window.

This transaction will fail if:

Augur is not currently in a halted state.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

Returns:

augur.api.FeeWindow.withdrawInEmergency(p)

If a critical bug or vulnerability is found in Augur, the Augur development team can put Augur into a halted state until the issue is resolved. In such instances, most regularly-used functions in Augur’s backend will become unuseable until the system is returned to its normal state. When this happens, users can call the withdrawInEmergency function to withdraw their Participation Tokens and convert them into Reputation Tokens.

This transaction will fail if:

Augur is not currently in a halted state.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

augur.api.FillOrder.publicFillOrder(p)

Attempts to Fill p._amountFillerWantsShare Units for Orderp._orderId. If p._amountFillerWants is enough to Fill the Order completely, the Order will be removed from the Order Book. Otherwise, it will be adjusted to only include the remaining amount after Filling the p._amountFillerWants value that the Filler requests. This transaction will trigger an OrderFilled event if the Order is Filled without any errors.

Returns:

Initial Reporter Tx API

// Initial Reporter Transaction API Examples:// The Ethereum address of a Market's InitialReporter contract // can be obtained by calling `augur.api.Market.getInitialReporter`.varinitialReporterAddress="0x0c77f6af7b3b5fed8ca980414a97c62da283098a";augur.api.InitialReporter.forkAndRedeem({tx:{to:initialReporterAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});augur.api.InitialReporter.redeem({"":initialReporterAddress,// This parameter's key must be the empty string, and its value can be any address-length string.tx:{to:initialReporterAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});augur.api.InitialReporter.transferOwnership({_newOwner:"0x9998ff3e9ce1c0459b309fac6dd4e69229b91777",tx:{to:initialReporterAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});augur.api.InitialReporter.withdrawInEmergency({tx:{to:initialReporterAddress,gas:"0x632ea0"},meta:{accountType:"privateKey",address:"0x913dA4198E6bE1D5f5E4a40D0667f70C0B5430Ec",signer:[252,111,32,94,233,213,105,71,89,162,243,247,56,81,213,103,239,75,212,240,234,95,8,201,217,55,225,0,85,109,158,25],},onSent:function(result){console.log(result);},onSuccess:function(result){console.log(result);},onFailed:function(result){console.log(result);}});

augur.api.InitialReporter.forkAndRedeem(p)

Causes a Child Universe to be created for the Outcome of the Initial Report and migrates the REPStaked by the Initial Reporter to the Child Universe. This transaction can be called at any time after the Fork has begun (including after the Market has been Finalized). When called by a user who who submitted the Initial Report, it will also transfer the REP Staked on the Initial Report’s Outcome to the Initial Reporter of the Forked Market.

Parameters:

p (Object) Parameters object.

**p[""] (string) The redeem function in InitialReporter.sol requires an unnamed parameter to be passed in so that it can fulfill an interface. When calling augur.api.InitialReporter.redeem, this parameter should be passed using the empty string as the key. Since this function does not actually use this parameter, it’s value can be any address-length string. (Please refer to example code for this function.)

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

Returns:

augur.api.InitialReporter.withdrawInEmergency(p)

If a critical bug or vulnerability is found in Augur, the Augur development team can put Augur into a halted state until the issue is resolved. In such instances, most regularly-used functions in Augur’s backend will become unuseable until the system is returned to its normal state. When this happens, Initial Reporters can call the withdrawInEmergency function to withdraw the REP they Staked on the Initial ReportOutcome (in cases where the First Public Reporter submitted the Initial Report instead of the Designated Reporter).

This transaction will fail if:

Augur is not currently in a halted state.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

augur.api.Market.contribute(p)

Contributes p._amountREP to the Dispute Crowdsourcer represented by Payout Setp._payoutNumerators and p._invalid in order to help Challenge the Market’s Tentative Outcome. If the amount of REP in the Dispute Crowdsourcer plus p._amount is greater than the total REP required to fill the Dispute Bond, this function will only contribute the remaining amount of REP required to fill the Dispute Bond on behalf of the caller.

This transaction will trigger a DisputeCrowdsourcerContribution event if it executes without any errors. It will also trigger a DisputeCrowdsourcerCompleted event if the Dispute Bond is successfullly filled, and it will trigger a UniverseForked event if enough REP has been Staked in the Dispute Crowdsourcer to cause the Market to Fork.

The Outcome specified by p._payoutNumerators and p._invalid is already the Tentative Outcome of the Market.

p._invalid is true and the Numerators in p._payoutNumerators are not all the same value. (For information about what the Payout Set should look like for an Invalid Market, refer to the Invalid Outcome glossary entry.)

p._invalid is true and the Numerators in p._payoutNumerators are not all the same value. (For information about what the Payout Set should look like for an Invalid Market, refer to the Invalid Outcome glossary entry.)

Returns:

augur.api.Market.migrateThroughOneFork(p)

Migrates the Market into a winning Child Universe from a ForkedParent Universe. When a Fork occurs, there is a Fork Period, wherein REP holders migrate their REP to the Universe they want to continue in. Once the Fork Period ends, the Child Universe with the most REP migrated to it is declared the Winning Universe. Calling this function attempts to move the Market from a Parent Universe to the Winning Universe after it’s been decided. This function also migrates the No-Show Bond to the winning Universe and migrates REP staked in the InitialReporter contract to the ReputationToken contract associated with the Child Universe.

Returns:

augur.api.Market.transferOwnership(p)

Changes the owner of the Market from the current owner to p._newOwner. This transaction will trigger a MarketTransferred event, which will record the Market and Universe it belongs to, as well as the old owner’s address and the new owner’s address.

This transaction will fail if:

msg.sender isn’t the owner of the Market.

Parameters:

p (Object) Parameters object.

p._newOwner (string) Ethereum address of the desired new owner of the Market, as a 20-byte hexadecimal value.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.

Returns:

augur.api.Market.withdrawInEmergency(p)

If a critical bug or vulnerability is found in Augur, the development team can put it the system into a halted state until the issue is resolved. In such instances, most regularly-used functions in Augur’s backend will become unuseable until the system is returned to its normal state. When this happens, users can call the withdrawInEmergency function to withdraw their Reputation Tokens from a particular Market.

This transaction will fail if:

Augur is not currently in a halted state.

Parameters:

p (Object) Parameters object.

p.tx (Object) Object containing details about how this transaction should be made.

p.tx.to (string) Ethereum contract address on which to call this function, as a 20-byte hexadecimal string.

p.tx.gas (string) Gas limit to use when submitting this transaction, as a hexadecimal string.