Introduction to FX via API

The new FX services enables Partner Portal API subscriptions to view exchange rates (FX RFQ) and execute the conversion of USD and 30+ foreign currencies in real-time (FX Trade). Once the FX trade has been executed, the foreign currency is immediately available for distribution through a foreign currency payment.

Introductions to each relevant endpoint are included below and should be used in conjunction with our online documentation found here. Additionally, all FX endpoint Accept headers also include the option to include Hateoas links in the request response which can be useful in navigating to other FX services.

POST fx/quote

The POST fx/quote endpoint provides the option to buy or sell foreign currency from/to Silvergate. For a list of eligible currency pairs, please contact [email protected]

  • Buying foreign currency:
    • The ability to buy foreign currency from Silvergate in exchange for USD withdrawn from an owned Silvergate account.
  • Selling foreign currency:
    • The ability to sell foreign currency to Silvergate in exchange for USD deposited into an owned Silvergate account.

Get started with the fx/quote endpoint and select the appropriate Accept header for the request. The fx/quote endpoint has two Accept header types from which to choose from:

  • Request for Quote ("RFQ")

    • application/vnd.silvergate.quote+json (or application/vnd.silvergate.quote.hateoas+json for links)
      • This Accept header can be used to review exchange market prices.
      • The response returned will include the exchange rate for the currency pair selected as well as the information needed to execute upon the quote.

  • Market Order

    • application/vnd.silvergate.marketorder+json (or application/vnd.silvergate.marketorder.hateoas+json for links)
      • This Accept header can be used to execute an FX trade at the current market price.
      • The response returned will include the contract id (trade id) for the agreement of currency exchange with Silvergate.

POST fx/trade

The POST fx/trade endpoint provides the ability to accept the quote received in an RFQ. A valid quote id must be provided to execute the trade. Valid quote IDs from RFQ cannot be:

  • Indicative
    • Indicative quotes are informative only. Refer to the “is_indicative” and “indicative_reason” fields from the fx/quote response to determine if your “quote_id” is valid.
  • Expired, or
    • Each RFQ response includes a “quote_expiration”. If the current date/time exceeds the “quote_expiration”, the “quote_id” becomes invalid.
  • Previously used
    • A unique “quote_id” is required for each POST fx/trade request.

Accept header is application/vnd.silvergate.tradeexecution+json or else application/vnd.silvergate.tradeexecution.hateoas+json to get Hateoas links.

POST fx/payment

The POST fx/payment endpoint provides the ability to send foreign currency associated with an executed FX trade via a wire payment.

In addition to Accept headers, the fx/payment endpoint has two Content-Type header types from which to choose. One of each header type must be passed.

  • For Existing Connection payments:

    • Accept header must be either application/vnd.silvergate.fxpaymentrequest+json or application/vnd.silvergate.fxpayment.hateoas+json
    • Content-Type header: application/vnd.silvergate.fxpaymentrequest+json
      • This header is required when the “external_account_type” identified in the trade execution equals “owned”.
      • The “external_account_id” field must contain a valid Owed account id for the payment.
        • See GET connections below for more information regarding using existing connections as fx/payment beneficiaries.
      • The response returned will include the information needed to submit the PATCH payment request, required to complete the payment.

  • For Ad Hoc payments:

    • Accept header must be either application/vnd.silvergate.fxpaymentrequest+json or application/vnd.silvergate.fxpayment.hateoas+json
    • Content-Type header: application/vnd.silvergate.adhocfxpaymentrequest+json
      • This header can be used when the “external_account_type” identified in the trade execution does not equal “owned” and an existing third-party connection does not exist.
      • The response returned will include the information needed to submit the PATCH payment request, required to complete the payment.

GET payment/instructions

The GET payment/instructions endpoint provides the ability to retrieve wire payment instructions for a specific FX trade. If you are selling foreign currency, this endpoint will provide specific instructions to include in the wire payment being sent to Silvergate.

Accept header is application/vnd.silvergate.paymentinstructions+json or else application/vnd.silvergate.paymentinstructions.hateoas+json to get Hateoas links.

GET fx/trade(s)

The GET fx/trade(s) endpoint provides the ability to retrieve a history of executed FX trades. Historical search criteria includes trade-id and date range.

Accept header is application/vnd.silvergate.trade+json or else application/vnd.silvergate.trade.hateoas+json to get Hateoas links.

GET connections

The GET connections endpoint provides the ability to retrieve “external_account_id”s which can be used as beneficiary details in the POST fx/payment endpoint. Connections must be created and maintained from the Silvergate Portal. The connections endpoint has three Accept header types from which to choose:

  • Connections
    • application/vnd.silvergate.connections+json (or application/vnd.silvergate.connections.hateoas+json for links)
      • This Accept header can be used to retrieve all connections (third-party and owned accounts).
  • Third Party Contacts
    • application/vnd.silvergate.contacts+json (or application/vnd.silvergate.contacts.hateoas+json for links)
      • This Accept header can be used to filter for third-party contacts and accounts.
  • Owned Accounts
    • application/vnd.silvergate.externalaccounts+json (or application/vnd.silvergate.externalaccounts.hateoas+json for links)
      • This Accept header can be used to filter for owned accounts external to Silvergate.
      • An existing owned account must be used in the POST fx/payment endpoint for FX trades where “external_account_type” equals “owned”.