1. Introduction

This document describes how to programmatically interact with the e-gold^® web site (located at http://www.e-gold.com). Interaction of this sort might be useful to those desiring to automate e-gold payments, verify a particular transaction has occurred, or pull account history into a third party program.

This document describes the fields and parameters required for interfacing to the e-gold system to perform these actions.

1.1 Intended Audience

This document is intended to be utilized by technical personnel with programming knowledge; specifically with a working knowledge of HTML forms.

1.2 Overview of e-gold^® Automation Tasks and Implementation

1.2.1 The e-gold^® spend.

The e-gold^®spend is a transaction initiated by the owner of an e-gold^®account to transfer e-metal^® to another e-gold^® account. (An e-gold^® account holder can never “pull” e-metal^® from another account; only the owner may initiate value transfer).

Normally, an e-gold^®spend is performed interactively by the account holder using a web (or PCS/WAP phone) browser to submit payment information via HTML (HDML/WML) form input.

The user interested in automation of this task may require unattended spending, or repetitive spending without the manual data re-entry this would require using the browser method.

1.2.2 e-gold^® account history.

The e-gold^® account history for a particular account contains all the transactions for the account. (e.g. e-metal^® payments received, made, storage fees assessed, etc).

Again, this act of viewing this history is normally performed interactively via a web browser.

The user interested in automation of this task may require verification of a particular transaction (possibly an automated spend, or receipt of payment via the e-gold shopping cart interface [SCI]).

1.2.3 e-gold^® account balance.

The e-gold^® account balance for a particular account is the current weight in ounces of each particular e-metal^® held in the account.

The balance is normally viewed using a browser.

The user interested in automation of balance may wish to display their balance or derived information on their web site.

1.2.4 e-gold^® exchange rates.

Although e-gold Ltd. Does not make a market in exchange, it does maintain a set of exchange rates for denominating e-metal^® spends in various currency amounts. (i.e. spend 1 USD worth of e-gold^®).

Users normally view the exchange rates page with a web browser, or enter currency equivalents when performing an e-metal^® spend not denominated in weight units.

The user interested in automation of this task may wish to perform calculations based on the current (or past) exchange rates used on the e-gold^® system.

1.2.5 Implementation

The user wishing to implement e-gold^® automation functionality has several options for implementing the task at hand. The language and platform chosen for the task must provide the following functionality:

1. Support for HTTPS form submission to a remote host.

2. Support for examining returned data for results.

Security Notes:

1. Do not embed your e-gold account passphrase in your automation program. Rather, prompt the user for the passphrase when the program runs.

2. Examine your automation program closely for problems. You are just as responsible for e-metal^® transactions initiated by an automation program as if you had entered the transaction by hand. (i.e. e-metal^® spends are not reversible regardless of the initiation method).

2. Automation Details

This section provides detailed information to allow a programmer to interface his automation program to the e-gold^® payment system.

In general, input fields are provided to the given URL via either an HTML form of the POST or GET variety. For instance a GET style request to retrieve the balance of e-metal^® account 101574 might look like:

https://www.e-gold.com/acct/balance.asp?AccountID=101574&Passphrase=This1isnotReal

The history and exchange rate data is returned in comma delimited format to the requestor. The balance, spend, and preview URLs return result data in hidden fields embedded in normal HTML. For example, the above balance request might return:

…
<td align=right><font face="Arial, Helvetica, sans-serif" size="2">225.7436</font></td>
<input type=hidden name=Gold_Ounces value="7.257937">
<input type=hidden name=Gold_Grams value="225.7436">
<td align=right><font face="Arial, Helvetica, sans-serif" size="2">1,975.61</font></td>
…

The caller can ignore all the HTML fields and pull out the return values from the hidden fields. (See the example scripts).

2.1 e-metal^® spend

An e-metal^® spend may be performed by doing an HTML form post of GET or POST variety to the URL: https://www.e-gold.com/acct/confirm.asp

The following input fields should be used:

Input Fields for submit to https://www.e-gold.com/acct/confirm.asp
Input Field Name	Description	Example Value
AccountID	e-metal^® account number (payer)	100079
PassPhrase	e-metal^® account passphrase	This1isnotReal
Payee_Account	e-metal^® account to spend to	100997
Amount	Amount to be spent. Must be positive numerical amount. Also must equate to at least 0.000010 ounces at current exchange rates.	5.15
PAY_IN	Code defining units payment is to be denominated in. Must be one of 1, 2, 33, 41, 44, 49, 61, 81, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 8888, 9999. 1=US Dollars, 2=Canadian Dollars, 33=French Francs, 41=Swiss Francs, 44=British Pounds, 49=Deutsche Marks, 61=Australian Dollars, 81=Japanese Yen, 85=Euro, 86=Belgian Franc, 87=Austrian Schilling, 88=Greek Drachma, 89=Spanish Peseta, 90=Irish Pound, 91=Italian Lira, 92=Luxembourg Franc, 93=Dutch Guilder, 94=Portuguese Escudo, 95=Finnish Markka, 96=Estonian Kroon, 97=Lithuanian Litas, 98=CFA Franc BEAC, 99=CFA Franc BCEAO, 8888=grams, 9999=ounces (troy).	1
WORTH_OF	e-metal^® name to spend. Must be one of “Gold”, “Silver”, “Platinum”, “Palladium”.	Gold
Memo	Up to 50 characters to be placed in memo section of transaction. The memo is visible to both payer and payee.	Thanks for dinner.
ACTUAL_PAYMENT_OUNCES	Numerical weight amount of payment as previewed. Formatted to 6 decimal places. Not required if IGNORE_RATE_CHANGE set. If present, must equate to computed weight of spend for spend to occur. (Used to detect updated exchange rates since spend was previewed).	0.017167
IGNORE_RATE_CHANGE	Spend will only occur if ACTUAL_PAYMENT_OUNCES input matches computed weight of spend. If IGNORE_RATE_CHANGE is present (value does not matter), spend will occur regardless of ACTUAL_PAYMENT_OUNCES input.	y
PAYMENT_ID	Optional merchant reference number. If present, this string of up to 50 characters is placed in the transaction. Payer and/or payee may search/query account history for this value.	ID 55789-Ab9@

Output from the confirm.asp page will include HTML with embedded hidden form fields for retrieving results of the spend. These are:

Output Fields from submit to https://www.e-gold.com/acct/confirm.asp
Output Field Name	Description	Example Value
ERROR	Spend did not occur if this field present. Text description of error.	The UNITS 555 specified is not valid.
Payee_Account	e-metal^® account number of recipient of spend.	100997
ACTUAL_PAYMENT_OUNCES	Amount of e-metal^® spent from spender. Formatted to 6 decimal places. (Note that the receiver of the e-metal^® spend is charged a fee to receive the spend and will not net this complete amount. See PAYMENT_FEE_OUNCES field).	0.017167
PAYMENT_FEE_OUNCES	Fee charged to recipient of payment by e-gold Ltd in ounces of e-metal^®. Formatted to 6 decimal places.	0.000172
PAYMENT_AMOUNT	Numerical amount of spend as entered. This is the same value as the Amount input field.	5.15
PAYMENT_UNITS	Code defining units payment was denominated in. Will be one of 1, 2, 33, 41, 44, 49, 61, 81, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 8888, 9999 and will match the PAY_IN input field. 1=US Dollars, 2=Canadian Dollars, 33=French Francs, 41=Swiss Francs, 44=British Pounds, 49=Deutsche Marks, 61=Australian Dollars, 81=Japanese Yen, 85=Euro, 86=Belgian Franc, 87=Austrian Schilling, 88=Greek Drachma, 89=Spanish Peseta, 90=Irish Pound, 91=Italian Lira, 92=Luxembourg Franc, 93=Dutch Guilder, 94=Portuguese Escudo, 95=Finnish Markka, 96=Estonian Kroon, 97=Lithuanian Litas, 98=CFA Franc BEAC, 99=CFA Franc BCEAO, 8888=grams, 9999=ounces (troy).	1
PAYMENT_METAL_ID	Code of e-metal^® used in spend. Will be 1 for Gold, 2 for Silver, 3 for Platinum, 4 for Palladium.	1
PAYER_ACCOUNT	e-metal^® account of spender	100079
USD_PER_OUNCE	Exchange rate of e-metal^® used in this transaction in US dollars per ounce.	300.00
PAYMENT_BATCH_NUM	e-gold batch number generated for this transaction. Payer and/or payee may query/search account history by this number.	758094
PAYMENT_ID	Optional merchant reference number. If present on input, this string of up to 50 characters is returned on output. Payer and/or payee may search/query account history for this value.	ID 55789-Ab9@

2.2 e-metal^® spend preview/verification

An e-metal^® spend preview may be performed by doing an HTML form post of GET or POST variety to the URL: https://www.e-gold.com/acct/verify.asp

This preview / verification function might be used to check the validity of a potential spend, or to determine the actual payment ounces of a potential spend prior to executing it. Note that posting to this location does not actually perform any transfer of e-metal^®.

The following input fields should be used:

Input Fields for submit to https://www.e-gold.com/acct/verify.asp
Input Field Name	Description	Example Value
AccountID	e-metal^® account number (payer)	100079
PassPhrase	e-metal^® account passphrase	This1isnotReal
Payee_Account	e-metal^® account to spend to	100997
Amount	Amount to be spent. Must be positive numerical amount. Also must equate to at least 0.000010 ounces at current exchange rates.	5.15
PAY_IN	Code defining units payment is to be denominated in. Must be one of 1, 2, 33, 41, 44, 49, 61, 81, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 8888, 9999. 1=US Dollars, 2=Canadian Dollars, 33=French Francs, 41=Swiss Francs, 44=British Pounds, 49=Deutsche Marks, 61=Australian Dollars, 81=Japanese Yen, 85=Euro, 86=Belgian Franc, 87=Austrian Schilling, 88=Greek Drachma, 89=Spanish Peseta, 90=Irish Pound, 91=Italian Lira, 92=Luxembourg Franc, 93=Dutch Guilder, 94=Portuguese Escudo, 95=Finnish Markka, 96=Estonian Kroon, 97=Lithuanian Litas, 98=CFA Franc BEAC, 99=CFA Franc BCEAO, 8888=grams, 9999=ounces (troy).	1
WORTH_OF	e-metal^® name to spend. Must be one of “Gold”, “Silver”, “Platinum”, “Palladium”.	Gold
Memo	Up to 50 characters to be placed in memo section of payment. The memo is visible to both payer and payee.	Thanks for dinner.
PAYMENT_ID	Optional merchant reference number. If present on input, this string of up to 50 characters is returned on output. Payer and/or payee may search/query account history for this value.	ID 55789-Ab9@

Output from the verify.asp page will include HTML with embedded hidden form fields for retrieving results of the spend. These are:

Output Fields from submit to https://www.e-gold.com/acct/verify.asp
Output Field Name	Description	Example Value
ERROR	Verification is unsuccessful and did not occur if this field present. Text description of error.	The UNITS 555 specified is not valid.
Payee_Account	e-metal^® account number of recipient of spend.	100997
ACTUAL_PAYMENT_OUNCES	Actual amount of e-metal^® that would be spent from spender. Formatted to 6 decimal places. (Note that the receiver of the e-metal^® spend is charged a fee to receive the spend and will not net this complete amount. See PAYMENT_FEE_OUNCES field).	0.017167
PAYMENT_AMOUNT	Numerical amount of spend as entered. This is the same value as the Amount input field.	5.15
PAYMENT_UNITS	Code defining units payment is denominated in. Will be one of 1, 2, 33, 41, 44, 49, 61, 81, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 8888, 9999 and will match the PAY_IN input field. 1=US Dollars, 2=Canadian Dollars, 33=French Francs, 41=Swiss Francs, 44=British Pounds, 49=Deutsche Marks, 61=Australian Dollars, 81=Japanese Yen, 85=Euro, 86=Belgian Franc, 87=Austrian Schilling, 88=Greek Drachma, 89=Spanish Peseta, 90=Irish Pound, 91=Italian Lira, 92=Luxembourg Franc, 93=Dutch Guilder, 94=Portuguese Escudo, 95=Finnish Markka, 96=Estonian Kroon, 97=Lithuanian Litas, 98=CFA Franc BEAC, 99=CFA Franc BCEAO, 8888=grams, 9999=ounces (troy).	1
PAYMENT_METAL_ID	Code of e-metal^® used in preview. Will be 1 for Gold, 2 for Silver, 3 for Platinum, 4 for Palladium.	1
PAYER_ACCOUNT	e-metal^® account of spending account.	100079
USD_PER_OUNCE	Exchange rate of e-metal^® currently in effect in US dollars per ounce.	300.00
PAYMENT_ID	Optional merchant reference number. If present on input, this string of up to 50 characters is returned on output. Payer and/or payee may search/query account history for this value.	ID 55789-Ab9@

2.3 e-metal^® history

The transaction history for an e-gold^® account can be retrieved in CSV (Comma Separated Value) format using the URL: https://www.e-gold.com/acct/historycsv.asp

The following input fields should be used:

Input Fields for submit to https://www.e-gold.com/acct/historycsv.asp
Input Field Name(s)	Description	Example Value(s)
AccountID	e-metal^® account number (payer)	100079
PassPhrase	e-metal^® account passphrase	This1isnotReal
startmonth, startday, startyear	These three fields define the starting day to gather account history from. Month should be a number from 1 to 12, day should be a number from 1 to 31 and year should be a 4 digit number from 1996 onward.	12 1 1999
endmonth, endday, endyear	These three fields define the ending day to gather account history from. Month should be a number from 1 to 12, day should be a number from 1 to 31 and year should be a 4 digit number from 1996 onward. History will be provided for records from the beginning of the start date fields to the end of the end date fields. For instance, the example values would retrieve one complete month of data for the month of December 1999.	12 31 1999
paymentsmade	If present on input, e-metal^® payments made are included in the history display. To not include e-metal^® payments made, do not include this as an input field.	1
paymentsreceived	If present on input, e-metal^® payments received are included in the history display. To not include e-metal^® payments received, do not include this as an input field.	1
inexchanges	If present on input, InExchange transactions are included in the history display. To not include InExchange transactions, do not include this as an input field.	1
outexchanges	If present on input, OutExchange transactions are included in the history display. To not include OutExchange transactions, do not include this as an input field.	1
bailments	If present on input, Direct Bailment transactions are included in the history display. To not include Direct Bailment transactions, do not include this as an input field.

Date	Description of Changes	Affected Sections
April 5, 2007	Added two currencies to lists of currencies: XOF (CFA Franc BCEAO) and XAF (CFA Franc BEAC). Note trademark on e-metal^®	2.1, 2.2, 2.3, 2.5,
September 23, 2004	Replaced contact email with URL.	Cover
December 23, 2001	Additional currencies for spend denominations including Euro.	2.1, 2.2, 2.3, 2.5
January 30, 2001	Correction of registered trademark symbol ^®	all
January 25, 2001	Inconsequential tweaks here and there.
September 6, 2000	Initial document	all

1.2 Overview of e-gold® Automation Tasks and Implementation

1.2.1 The e-gold® spend.

1.2 Overview of e-gold^® Automation Tasks and Implementation

1.2.1 The e-gold^® spend.