GET /history/incoming

Return a list of transactions made from or to the exchange.

Incoming transactions must contain a valid reserve public key. If a bank transaction does not conform to the right syntax, the wire gateway must not report it to the exchange, and send funds back to the sender if possible.

Request:

Query Parameters:

• limit – Optional. At most return the given number of results. Negative for descending by row_id, positive for ascending by row_id. Defaults to -20. Since protocol v2.

• offset – Optional. Starting row_id for pagination. Since protocol v2.

• timeout_ms – Optional. Timeout in milliseconds, for long-polling, to wait for at least one element to be shown. Only useful if limit is positive. Since protocol v2.

• delta – Optional. Deprecated in protocol v2. Use limit instead.

• start – Optional. Deprecated in protocol v2. Use offset instead.

• long_poll_ms – Optional. Deprecated in protocol v2. Use timeout_ms instead.

Response:

200 OK:

JSON object of type IncomingHistory.

204 No content:

There are not transactions to report (under the given filter).

400 Bad request:

Request malformed. The bank replies with an ErrorDetail object.

401 Unauthorized:

Authentication failed, likely the credentials are wrong.

404 Not found:

The endpoint is wrong or the user name is unknown. The bank replies with an ErrorDetail object.

Details:

interface IncomingHistory {
  // Array of incoming transactions.
  incoming_transactions: IncomingBankTransaction[];

  // Full payto URI to identify the receiver of funds.
  // This must be one of the exchange's bank accounts.
  // Credit account is shared by all incoming transactions
  // as per the nature of the request.
  credit_account: string;
}

// Union discriminated by the "type" field.
type IncomingBankTransaction =
| IncomingKycAuthTransaction
| IncomingReserveTransaction
| IncomingWadTransaction;

// Since protocol **v1**.
interface IncomingKycAuthTransaction {
  type: "KYCAUTH";

  // Opaque identifier of the returned record.
  row_id: SafeUint64;

  // Date of the transaction.
  date: Timestamp;

  // Amount received before credit_fee.
  amount: Amount;

  // Fee paid by the creditor.
  // If not null, creditor actually received amount - credit_fee
  // @since **v3**
  credit_fee?: Amount;

  // Full payto URI to identify the sender of funds.
  debit_account: string;

  // The account public key extracted from the transaction details.
  account_pub: EddsaPublicKey;

  // The authorization public key used for mapping
  // @since **v5**
  authorization_pub?: EddsaPublicKey;

  // Signature of the account public key using the authorization private key
  // @since **v5**
  authorization_sig?: EddsaSignature;
}

interface IncomingReserveTransaction {
  type: "RESERVE";

  // Opaque identifier of the returned record.
  row_id: SafeUint64;

  // Date of the transaction.
  date: Timestamp;

  // Amount received before credit_fee.
  amount: Amount;

  // Fee payed by the creditor.
  // If not null, creditor actually received amount -
  // @since **v3**
  credit_fee?: Amount;

  // Full payto URI to identify the sender of funds.
  debit_account: string;

  // The reserve public key extracted from the transaction details.
  reserve_pub: EddsaPublicKey;

  // The authorization public key used for mapping
  // @since **v5**
  authorization_pub?: EddsaPublicKey;

  // Signature of the reserve public key using the authorization private key
  // @since **v5**
  authorization_sig?: EddsaSignature;
}

interface IncomingWadTransaction {
  type: "WAD";

  // Opaque identifier of the returned record.
  row_id: SafeUint64;

  // Date of the transaction.
  date: Timestamp;

  // Amount received before credit_fee.
  amount: Amount;

  // Fee payed by the creditor.
  // If not null, creditor actually received amount - credit_fee
  // @since **v3**
  credit_fee?: Amount;

  // Full payto URI to identify the sender of funds.
  debit_account: string;

  // Base URL of the exchange that originated the wad.
  origin_exchange_url: string;

  // The reserve public key extracted from the transaction details.
  wad_id: WadId;
}