FX Home
 
Claims
All Accounts
Ticker
Summary
Mailing Lists

Your Account
Your Profile

Help

Contact Us

COPYRIGHT: this document may be freely redistributed in its entirety, including this copyright notice. Redistribution of parts of this document requires the consent of the editor, Ken Kittlitz (kittlitz AT ideosphere DOT com). All other rights reserved.

FXTP Command Set

Introduction

This document describes the Foresight Exchange Transport Protocol (FXTP) command set. FXTP is the protocol by which clients (web, telnet email, etc.) communicate with the FXTP server. The FXTP Overview describes the overall server structure and rationale behind FXTP; complete documentation on how to play the Foresight Exchange is also available.

Overview of Usage

Connecting to the FXTP Server

To use the Foresight Exchange, you send FXTP commands to the server via one of several ways:

  • using the webface. In this case, the FXTP commands are embedded in the CGI scripts that make up the pages, and you don't need to know the actual FXTP syntax. This option will suffice for many players.
  • using the connection server. This is the "raw" FXTP server, suitable for use by automated agents, Java applets, ActiveX controls etc.
  • using the telnet or email servers. Both provide handy shortcuts for FXTP commands, and format the output of some commands. These servers are intended for direct use by people, as opposed to programs.

This document focuses on the connection and telnet/email servers.

Basic Command Structure

FXTP commands are all of the form:

name argument1,argument2,...

where name is the name of command and argument1, argument2 etc. are its arguments. All "raw" FXTP commands as supported by the connection server are terminated by a newline character (ASCII value 10); that is, no command can span multiple lines. The telnet and email servers allow more humane ways of entering some commands.

An example of an FXTP command is:

claim_info Foobar,short,judge

which would return the short description and the judge of claim "Foobar". Exactly how the information is returned depends on the server being used.

FXTP Servers

FXTP servers allow you to send FXTP commands to the main database server. Other than the webface, which takes care of the FXTP commands for you, you have the choice of sending/receiving raw FXTP commands via the connection server, or formatted commands via the telnet or email servers.

Connection Server

The connection server runs on port 7001 of ideosphere.com It accepts "raw" FXTP commands, meaning that each command is terminated by a new-line, and returns raw output. The format of the output varies from command to command, however:

  • the status of the command is always returned as the first output line. The status line begins with a number: "2nn" indicates success; anything else indicates failure.
  • output is guaranteed to be terminated by a '.' character on a line by itself.

Note that each line of output is terminated by a newline character (ASCII value 10), not by a carriage return/newline combination.

For example, sending the FXTP command:

claim_info Foobar short,date_due

to the connection server might result in output like:

200 command OK, output follows...
This is the short description of claim "Foobar"...
1995/01/01
.

In other words, the claim status is the first line of output, the short description of the claim is returned as the second line, the claim's due date returned as the third line, and the terminating '.' as the third line.

To exit a connection server session, send the command bye.

The connection server is designed for use by programs such as automated agents and Java applets.

Telnet Server

The telnet server runs on port 7002 of ideosphere.com, and is designed to be used by people rather than programs. Like the connection server, it accepts FXTP commands as input; most are simple enough to be specified on one line, but it supports extensions for more complex commands, including alternate syntax, shortcuts, and. formatting of command output so that it is easier to interpret: for successful commands, the status line is not returned; for all command the terminating '.' line is stripped. Each line of output is terminated by a carriage return/newline pair (ASCII 10 + ASCII 12).You can identify the end of a command's output because the server displays the following prompt when it is ready to receive more input:

FXTP-telnet:

To exit a telnet server session, enter the command bye.

Email Server

The email server is available at fx@ideosphere.com, and is designed to be used by people rather than programs (though nothing prevents you from writing a program that uses it). Like the connection server, it accepts FXTP commands as input; most are simple enough to be specified on one line, but for more complex commands it supports extensions such as alternate syntax, shortcuts and formatting of command output so that it is easier to interpret.. For all command output, the server strips off the terminating '.'; in its response message, it indicates which output is associated with which command request.

If the server was unable to recognise any commands in the message, it will return the output for the help command.

Telnet and Email Server Extensions

Because the telnet and email servers are designed primarily for use by people rather than programs, they use some variations on the raw FXTP syntax. These fall into three categories: shortcuts, alternate syntax and output formatting.

Shortcuts

The only shortcut currently supported is login, which has the following syntax:

login uid,password

When this command is entered (either in a telnet server session, or as a line in a message to the mail server), subsequent commands that require a uid and/or a password can be typed in abbreviated form. For example, the person with uid 107 and password 'haha' would normally place orders command like this:

orders 107,haha,new Foobar B10@30

But using the login shortcut, he/she can send commands like:

login 107,haha

orders ,,new Foobar B10@30

Note that the commas that delimit the uid and password fields still have to be included. So, for example, the shortcut for the same user's account command:

account 107,-1

would be:

account ,-1

Commands that can be abbreviated using the login shortcut are: account, approve, claim, orders, set_email, profile, set_password, set_profile and user_info

Alternate Syntax

For ease of use, the telnet and email servers use alternate syntax for the following commands: claim.

Output Formatting

For ease of use, the telnet and email servers format the raw output of the following commands: account, claim, claim_info.

Types of Commands

FXTP commands can be broken down into several categories (some commands appear in more than category).

Registration/Administration Commands

The following commands are used to create or maintain your FX registration:

  • register: the first command you send, used to create a new account.
  • activate: confirms your registration
  • resend_id: resends the FX uid and password associated with your email address
  • set_email: changes the email address associated with your account.
  • set_password: changes your account's password
  • set_profile: sets one of your user profiles

Trading Commands

The major trading commands are:

  • orders: places orders on claims
  • account: retrieves your portfolio
  • ticker: retrieves the trading history of a claim or user
  • volume: retrieves the trading volume of claims for a specified trading period.
  • plot: plots the price of a claim for a specified trading period.

User Information Commnands

Commands that return information about users are:

  • list_uids: retrieves the set of user Ids (uids)
  • user_info: retrieves attributes of a specified user
  • ticker: retrieves a user's trading history
  • profile: retrieves a trading profile for a specific user.

Claim Information/Editing Commands

Commands that create, modify, or return information about a claim are:

  • change_claim_state: allows a judge to close a claim
  • claim: creates or modifies a claim.
  • list_claims: retrieves the list of claim symbols
  • claim_list: retrieves the list of claims associated with a specified keyword.
  • list_keyword: retrieves the list of possible claim keywords.
  • claim_info: retrieves attributes of a specified claim
  • ticker: retrieves a claim's trading history
  • volume: retrieves the trading volume of claims for a specified trading period.
  • plot: plots the price of a claim for a specified trading period.
  • approve: allows a player to signify that he/she is willing to be the judge of a claim.

Additionally, help is available for the regular expression syntax used to specify claims.

Miscellaneous Commands

  • help: returns FXTP help information.
  • time: returns the current server time.
  • bye: terminates a connection or telnet server session.

Command Descriptions

This section describes the FXTP commands in detail; commands are listed alphabetically.

Account

Retrieves a user's portfolio, as specified by a profile key or keyword (both are values that selects a set of claims).

Syntax

account uid,<profile_key | keyword>

Returns

The system time, user's nym, cash, networth and score. For each keyword selected, the keyword name. For each claim associated with the keyword, the claim symbol, user's holdings (0 if none), bid/ask/last price (on one line, separated by tabs), short description and user's booked orders (blank line if none).

The connection server returns the information one item per line; the telnet and email servers format the output.

Connection Server Example

account 107,-1
200 command OK, output follows...
1996/09/24 14:19:52
Killer
 883.01
 972.31
0.972
Category: Booked Orders
$vIF
1
68      70      70
Real $ Ver. of IF (<1.1.2000)
50Y@53,100N@10
BBQT
0
81      90      90
U.S. Abandons Net Censorship
50N@5                 
.

Activate

Activates a newly-registered account.

Syntax

     activate email,password

where:

  • email: is your email address
  • password: is the password returned by the register command.

Returns

The uid for your account. This information is also emailed to you.

Connection Server Example

activate ken@ideosphere.com,f2jK1v
200 command OK, output follows...
uid=107
.

Approve

Allows a player who has been asked to be the judge of a proposed to agree to this role and, implicitly, approve the claim's wording, due date, etc. Once a new claim has been approved and passed the mandatory waiting period, it becomes active for trading.

Syntax

     approve uid, password, claim

where:

  • uid: is the judge's uid
  • password: is the judge's password
  • claim: is the symbol of the claim to be approved

Returns

English sentence denoting success or failure of operation.

Connection Server Example

approve 107,haha,Foobar
200 command OK, output follows...
Claim 'Foobar' changed to APPROVED state.
.

Bye

Terminates a telnet server or connection server session.

Syntax

     bye

Connection Server Example

bye
205 over and out
Connection closed by foreign host.   

Change_claim_state

Allows the judge of an active claim to close it (render judgement).

Syntax

     change_claim_state password, claim, YES_payout

where:

  • password: is the judge's password
  • claim: is the symbol of the claim to be judged
  • YES_payout: is a number between 0 and 100 inclusive, indicating how much each YES coupon is worth. For example, 100 means each YES coupon is paid out at 1 credibill (NO coupons pay 0), 65 means each YES coupon is paid out at 0.65 credibills (NO coupons pay 0.35) and 0 means each YES coupon is worthless (NO coupons pay 1 credibill).

Returns

English sentence denoting success or failure of operation.

Connection Server Example

change_claim_state haha,Foobar,0
200 command OK, output follows...
Claim 'Foobar' changed to state RETIRED.
.

Claim

Creates a new claim or edits an existing claim. To create a claim, you must have at least in your account.

Syntax

     claim uid, password, symbol, short, long, judge, due,
           newsgroup, scaled, keyword, keyword,...

where:

  • uid: the creator's/editor's uid
  • password: the creator's/editor's password
  • symbol: the trading symbol of the claim
  • short: short description of claim
  • long: long description of claim
  • judge: UID of judge (i.e., must be registered player)
  • due: YYYY/MM or 'TBD'.
  • newsgroup: newsgroup for summary postings
  • scaled: 1 if claim is scaled (coupons may pay other than /home/ideo/ideafutures/fx/www/docs/fxtp_commands.cgi or ). 0 otherwise.
  • keyword: keywords (categories) that claim belongs to.

When creating a claim, optional fields (see usage), can be omitted (though you still need to include all commas).

Usage

Not all arguments need to be given. If creating a new claim, arguments not given are set to appropriate default values. If editing an existing claim, empty arguments do not affect existing claim values. To reset a claim value to its default, pass in 'none' for it.

When creating a new claim, the following fields are mandatory:

  • trading symbol
  • short description
  • long description

When editing an existing claim, the following rules apply:

    • nothing can be edited if the claim is retired.
  • otherwise:
    • keywords' and 'newsgroup' can always be edited.
    • due' can be edited if its value is 'TBD' or if claim state is PROPOSED.
    • 'judge', 'long', 'short', 'scaled' can be edited if and only if. claim state is PROPOSED.

Alternate Syntax

The raw FXTP syntax of claim (as supported by the connection server) is not human-friendly. The telnet and email servers use an alternate syntax of the form:

     claim uid,password
     tag: value
     tag: value
     end

where:

  • tag: is the name of a claim attribute. Legal attributes are "symbol", "short", "long", judge", "due", "scaled", "newsgroup" and "keywords".
  • value: is the value of a claim attributes. If the attribute can have more than one value, they may be separated with commas or newlines.

Optional fields may be omitted. Note that the long description may span multiple lines.

Telnet/Email Server Example

The following would create claim "Foobar" (assuming a claim with that symbol doesn't already exist).

claim 107,haha
symbol: Foobar
short: This is the Foobar claim
long: This is the long
description of the Foobar claim.
judge: 110
due:  1995/01/01
keywords: News:World News
News:US News
end

Claim_info

Returns information about the specified claim symbol regular expression.

Syntax

     claim_info (claim_regexp),attribute,attribute...]

where legal attributes are: short, judge, date_created, date_due, date_closed, long, bid, ask, last, owner, newsgroup, scaled, price, book, status, keywords.

Returns

Attribute values are returned in the order the attributes were specified; each value is terminated by a newline character. Note that some attributes may not have values (e.g., "date_closed" for active claims). In such case, only a newline character is returned..

  • short: claim short description.
  • judge, owner: UIDs.
  • date_created: in format YYYY/MM/DD
  • date_due: in format YYYY/MM/DD
  • date_closed: in format YYYY/MM/DD
  • long: claim's long description
  • judge_statement: Judge's statement about the claim
  • bid, ask, last: range from 0 to 100
  • price: returns bid, ask and last prices, separated by tabs
  • book: returns booked orders separated by commas Booked orders are all of the form uid symbol order (e.g., 107 BC96 B10@85).
  • status: state of claim. Values 0 to 100 inclusive is YES coupon payout (claim is closed); -1 indicates claim is proposed only; -2 indicates claim is active; -3 indicates claim is pending (past due date).
  • keywords: separated by tabs.

The telnet and email server split output lines at about 70 characters.

Connection Server Example

claim_info BC96,short,keywords,book
200 command OK, output follows...
Clinton re-elected in 96
Politics:US Politics
79 BC96 100@89,157 BC96 65@89,128 BC96 58@89,286 BC96 
1@89,199 BC96 106@88,162 BC96 100@88,157 BC96 79@86
79 BC96 100N@9,116 BC96 10N@9,199 BC96 99N@8
.

Claim_list

Returns the symbols of claims having the keywords specified by a regular expression

Syntax

     claim_list keyword_regexp

where:

  • keyword_regexp: is a regular expression describing claim keywords.

Returns

The symbols of the claims that are associated with the keyword(s). Each symbol is terminated by a newline character.

Connection Server Example (Extract)

claim_list News
200 command OK, output follows...
Cuba
SGAJ
seal
IrWh
16Jn
DKfg
OJvn
.

Help

Returns help information about the specified topic.

Syntax

     help topic

where:

  • topic: is a recognised help topic.

Topics include individual FXTP commands and information on FXTP servers, regular expressions etc. "help topics" returns a list of available topics.

List_claims

Returns all claim symbols.

Syntax

     list_claims

Returns

All claim symbols, including those of proposed or retired claims, each terminated by a newline.

List_keywords

Returns all valid keywords (claim categories).

Syntax

     list_keywords

Returns

All possible claim keywords, each terminated by a newline..

List_uids

Returns the UIDs of all FX users..

Syntax

     list_uids

Returns

All FX user UIDs, each terminated by a newline..

Login

Registers player's UID and/or password with an email or telnet server session.

Note: this is a telnet/email server extension, not a true FXTP command.

Syntax

     login [uid],[password]

Usage

Once the login command has been used, FXTP commands that require the player's uid and/or password may be abbreviated by leaving out those field values. The commas that delimit the fields must still be included however..

Telnet/Email Server Example (Extract)

orders 107,haha,new Foobar S5@40

login 107,haha
orders ,,del Foobar S5@40

Orders

Places, modifies or deletes claim coupon orders.

Syntax

     orders uid,password,order,[order,]...

where each "order" is of the form:

     <new|del|inc|dec> claim [B|S]quantity@price

and:

  • claim: is a claim symbol
  • B: indicates coupons are to be bought (default)
  • S: indicates coupons are to be sold.
  • quantity: is a number > 0
  • price: ranges from 1 to 99.

Usage

The new specifier adds a new order to the book. An error is returned if you already have an order at the same price.

The del specifier deletes an existing order. An error is returned if you do not have such an order on the book.

The inc specifier increments the existing order at the specified price by the specified quantity. An error is returned if you do not have an existing order at the specified price.

The dec specifier decrements the existing order at the specified price by the specified quantity. An error is returned if you do not have an existing order at the specified price.

Returns

English sentences describing the success or failure of the order(s). If successful, the orders may be added to the book or cause transactions to occur (if they match existing orders of the opposite type).

Connection Server Example

orders 107,haha,new FooBar B10@20
200 command OK, output follows...
order 'new FooBar 10@20' added to book.
.

Plot

Plots the price of a claim over a specified time period.

Syntax

     plot claim,[start_date],[end_date],<GIF|ASCII>

where:

  • claim: is a claim symbol
  • start_date: in form YYYY/MM/DD; default is claim's creation date
  • end_date: in form YYYY/MM/DD; default is current date.
  • GIF: indicates a GIF plot should be generated.
  • ASCII: indicates an ASCII plot should be generated.

Returns

If an ASCII plot was requested, it will be returned in the output. If a GIF plot was requested, a URL will be returned.

Connection Server Example

plot Foobar,,,GIF
200 command OK, output follows...
http://www.ideosphere.com/ideosphere/fx/plot/foobar.gif
.

Profile

Returns a specified user profile.

Syntax

     profile uid,profile_key

where:

  • profile_key: is a number between 0 and 5

Returns

The associated profile.

Connection Server Example

profile 107,1
200 command OK, output follows...
K+Arts & Entertainment:Entertainment Technology K+Arts & Entertainment:Movies

.

Register

Registers a new user.

Syntax

     register email,nym,privacy

where:

  • email: is the user's email address
  • nym: will be the user's "game name"
  • privacy: either 0 or 1. If 1 (set) the user's email address will not be visible to other players (though his/her nym will be).

Returns

If the email address appears valid, and neither the email address nor nym is in use by another player, an email message is sent containing an initial password. The password can then be used to activate the account.

Connection Server Example

register ken@ideosphere.com,Killer,0
200 command OK, output follows...
Password has been sent to ken@ideosphere.com by email.

.

Resend_id

Mails the FX UID and password associated with the specified email address to that email address. This is useful for people who have forgotten their passwords..

Syntax

     resend_id email

where:

  • email: is the email address of an FX player.

Returns

If the email address is associated with an FX account, the UID and password will be mailed to the address.

Set_email

Changes the email address of a registered user.

Syntax

     set_email uid,password,new_email
where:
  • new_email: is the new email address of the user.

Set_password

Changes the password of a registered user.

Syntax

     set_password uid,old_password,new_password

Set_profile

Sets the specified user profile.

Syntax

     set_profile uid,password,profile_key,profile

where:

  • profile_key: is a number between 1 and 5
  • profile: is the new profile

Returns

The associated profile.

Note: profile 0 can also be set, but represents the player's timezeone offset from GMT. As such, its value is numeric rather than a category string.

Connection Server Example

set_profile 107,password,1,K+News:World News
200 command OK, output follows...
Profile 1 set for user 107.

.

Ticker

Returns most recent ticker entries for the specified user or claim for the specified number of days.

Syntax

     ticker uid,claim[,days]

where:

  • uid: UID of FX user (omitted if claim is specified)
  • claim: claim symbol (omitted if uid is given)
  • days: number of days for which ticker entries should be extracted. Default is all relevant entries.

Returns

Ticker lines of the form:

     claim quantity price date/time pairs people buyer seller

where:

  • claim: claim symbol
  • quantity: quantity of coupons traded
  • price: price of trade
  • date/time: time of trade
  • pairs: coupon pairs in circulation after the trade people: number of people who hold coupons after the trade.
  • buyer: UID of buyer
  • seller: UID of seller

All items are separated by tab characters.

Connection Server Example

The following would retrieve the ticker entries for claim "BC96" that have occurred within the last day:

ticker ,BC96,1
200 command OK, output follows...
BC96  100  88  1996/09/25 14:04:36  5034  51  162  305
BC96  106  88  1996/09/25 14:04:36  5034  51  199  305
BC96  1  89  1996/09/25 14:02:53  5034  52  286  305
.

Time

Returns the current FX server time (GMT).

Syntax

     time

Returns

The FX server time (GMT), in format YYYY/MM/DD HH:MM:SS

User_info

Returns information about the specified user

Syntax

     user_info uid,attribute,attribute...]

where legal attributes are: nym, email, privacy, cash, networth, score, fees_in, fees_out, holdings, book, gid, allowance, date_signup, date_last_on

Returns

Attribute values are returned in the order the attributes were specified; each value is terminated by a newline character. Note that some attributes may not have values; in such case, only a newline character is returned..

  • allowance: total credibills user has received from allowance payments.
  • book: returns user's booked orders separated by commas Booked orders are all of the form uid symbol order (e.g., 107 BC96 B10@85).
  • cash: user's cash balance.
  • date_last_on: date user last performed an operation that required his/her password. In format YYYY/MM/DD
  • date_signup: in format YYYY/MM/DD
  • email: user's email address; only available if privacy is set to 0..
  • fees_in: income from other than trading profits and allowance (e.g., claim judging fee).
  • fees_out: credibills expended other than in trading (e.g., claim creation).
  • gid: currently unused.
  • holdings: in form claim:coupons separated by tab characters.
  • networth: consists of cash balance and current value of holdings.
  • nym: user's "game name".
  • privacy: flag, either 0 (or blank) or 1.
  • score: indicator of user's trading performance. Higher values are better.

Connection Server Example

user_info 107,email,cash,score,holdings
200 command OK, output follows...
Ken@lucifer.com
 883.01
0.963
$vIF:1  Immo:50 Cuba:50 Ches:20 BC96:-100       APPL:10 TWAC:50
.

Volume

Returns the number of coupons traded within the most recent N days, where N is specified by the command argument. Trading volume is summarised by claim.

Syntax

     volume [days]

where:

  • days: number of (most recent) days for which trading volume is to computed. Default is 14.

Returns

For each claim that had activity during the requested time period, its symbol and number of coupons traded, separated by a space character and terminated by a newline character.

Connection Server Example

volume 1
200 command OK, output follows...
TWAC 343
BC96 531
Ms.P 81
CLan 133
Cash 50
Ches 66
DLan 1
.

Other Topics

Keywords

Keywords (also knows as categories) are used to categorise FX claims. Each keyword describes a category (e.g., "Science & Technology:Space", "News:World News"), and each claim is associated with one or more keywords. Classifying claims by keywords helps users zero in on the types of claims that interest them; in particular, they can set up profiles containing specific keywords.

Commands that use or manipulate keywords are:

Profiles

Profiles allow users to select claims or categories of claims that they are interested in. Once defined, a profile can be used with the account command.

Profiles are specified by numeric keys; the following keys are supported:

  • -1: claims user has booked orders on
  • -2: claims user has holdings in
  • -3: claims for which user has holdings or booked orders
  • 0: user information (currently, only contains timezone offset from GMT).
  • 1 to 5: user-defined.

User-Defined Profiles

Profile keys 1 through 5 may be defined by the user via the set_profile command, which takes a key as its first argument and a value as its second argument. Profile values consist of tab-separated items of the form:

     K+keyword
     K-keyword
     C+claim
     C-claim

where:

  • K+keyword: will select the claims associated with the specified keyword
  • K-keyword: will omit the claims associated with the specified keyword.
  • C+claim: will select the claim with the specified symbol
  • C-claim: will omit the claim with the specified symbol.

Any number of such items can be specified in a profile.

Regular Expressions

Certain FXTP commands take Perl regular expressions for one or more of their arguments. A complete discussion of such expressions is beyond the scope of this document, but some of their features are:

  • the regular expression "abc" will match strings such as "abc", "12abcde", etc. This is the most common use of regular expressions in FX. For example, "News" used as a keyword regular expression would match both "News:US News" and "News:World News".
  • the '^' character can be used to anchor matches to the beginnings of strings. For example, "^abc" would match "abcde" but not "12abc".
  • the '$' character can be used to anchor matches to the ends of strings.
  • '.' matches any character in the string.
  • '*' matches 0 or more occurrences of the previous character.
  • other special characters include '/', '|' '+' and '?'.
  • '\' can be used to remove the special meaning of a character. For example, "\^abc" will match "12^abc".

Claim symbols or keywords containing characters such as '*' or '^' must be handled carefully. For example, since claim_info takes a regular expression as its first argument, special characters in claim symbols such as "$vIF" must be protected with '' characters:

     claim_info \$vIF,short

Commands that use regular expressions are:

  • account: second argument can be keyword regular expression
  • claim_info: first argument is claim symbol regular expression.
  • claim_list: first argument is keyword regular expression.

This page is maintained by Ken Kittlitz (kittlitz AT ideosphere DOT com). Last modified on 11/09/2003.