|
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.
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.
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.
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 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.
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.
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.
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.
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.
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
For ease of use, the telnet and email servers use alternate syntax for the following commands: claim.
For ease of use, the telnet and email servers format the raw output of the following commands: account, claim, claim_info.
FXTP commands can be broken down into several categories (some commands appear in more than category).
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
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.
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.
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.
- help: returns FXTP help information.
- time: returns the current server time.
- bye: terminates a connection or telnet server session.
This section describes the FXTP commands in detail; commands are listed alphabetically.
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
.
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
.
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.
.
Terminates a telnet server or connection server session.
Syntax
bye
Connection Server Example
bye
205 over and out
Connection closed by foreign host.
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.
.
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 ./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).
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
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
.
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
.
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.
Returns all claim symbols.
Syntax
list_claims
Returns
All claim symbols, including those of proposed or retired claims, each terminated by a newline.
Returns all valid keywords (claim categories).
Syntax
list_keywords
Returns
All possible claim keywords, each terminated by a newline..
Returns the UIDs of all FX users..
Syntax
list_uids
Returns
All FX user UIDs, each terminated by a newline..
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
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.
.
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
.
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
.
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.
.
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.
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.
Changes the password of a registered user.
Syntax
set_password uid,old_password,new_password
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.
.
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
.
Returns the current FX server time (GMT).
Syntax
time
Returns
The FX server time (GMT), in format YYYY/MM/DD HH:MM:SS
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
.
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
.
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 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.
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.
| 
