Skip to main content
API docs by Redocly

Grain API (1.0.0)

Download OpenAPI specification:Download

Grain Finance: support@grainfinance.co URL: https://developer.grainfinance.co License: Creative Commons Attribution 3.0 Terms of Service

Interact with Grain's servers for hedging transactions exposed to cross-currency on your platform

Customers

Customer objects are the foundation of integrating with Grain. They represent a customer of your business.
You can manage the inventory of transactions for such customers, and offer them automatic hedging for their foreign-exchange exposures.

Create

Creates or updates a customer on the Grain platform. If a customer with the given external ID already exists, the existing customer is updated; otherwise, a new customer is created. This endpoint is used for managing customers transacting through your platform, allowing you to later create transactions and hedges for these customers.

Authorizations:
api-key
Request Body schema: application/json
required

The payload required in order to create a customer

contactEmail
string (ContactEmail)

The email address of the company's primary contact

contactFullName
string

The name of the company's primary contact

contactPhoneNumber
string

The phone number of the company's primary contact

companyName
required
string

The legal name of the customer's company

companyAddress
string

The address of the company

companyCity
string

The city of the company

companyState
string

The state the company is in (US based)

companyCountry
required
string (CountryCode)

The alpha-2 ISO 3166 country code of the entity's country.

companyTaxId
string

The tax identification or registration number of the company

externalCustomerId
required
string

The id used to identify the customer within your platform

extraFields
object (CustomersExtraFieldsParam)

Additional fields that provide further details about the company. These fields should be specified as a valid JSON object.

Responses

Request samples

Content type
application/json
{
  • "contactEmail": "garrick@ollivanders.co.uk",
  • "contactFullName": "Garrick Ollivander",
  • "contactPhoneNumber": "+12125551234",
  • "companyName": "Ollivander's Wand Shop",
  • "companyAddress": "12 Diagon Alley",
  • "companyCity": "London",
  • "companyState": "London",
  • "companyCountry": "GB",
  • "companyTaxId": "123-45-6789",
  • "externalCustomerId": "630231b3ae0d7e9e5097ad35",
  • "extraFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

List

List all customers.

Authorizations:
api-key
query Parameters
external_customer_id
string

external_customer_id is the customer id, as identified within your system

page
number <double> (Page) >= 1

page number indicating which set of items to return

per_page
number <double> (PerPage) [ 1 .. 100 ]

The number of items in a page

Responses

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "pagination": {
    }
}

Update

Update an existing customer with new details.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The id of the customer within the Grain platform.

Request Body schema: application/json
required

The payload required in order to update a customer

contactEmail
string (ContactEmail)

The email address of the company's primary contact

contactFullName
string

The name of the company's primary contact

contactPhoneNumber
string

The phone number of the company's primary contact

companyName
string

The legal name of the customer's company

companyAddress
string

The address of the company

companyCity
string

The city of the company

companyState
string

The state the company is in (US based)

companyCountry
string (CountryCode)

The alpha-2 ISO 3166 country code of the entity's country.

companyTaxId
string

The tax identification or registration number of the company

externalCustomerId
string

The id used to identify the customer within your platform

extraFields
object (CustomersExtraFieldsParam)

Additional fields that provide further details about the company. These fields should be specified as a valid JSON object.

Responses

Request samples

Content type
application/json
{
  • "contactEmail": "garrick@ollivanders.co.uk",
  • "contactFullName": "Garrick Ollivander",
  • "contactPhoneNumber": "+12125551234",
  • "companyName": "Ollivander's Wand Shop",
  • "companyAddress": "12 Diagon Alley",
  • "companyCity": "London",
  • "companyState": "London",
  • "companyCountry": "GB",
  • "companyTaxId": "123-45-6789",
  • "externalCustomerId": "630231b3ae0d7e9e5097ad35",
  • "extraFields": {
    }
}

Response samples

Content type
application/json
{
  • "message": "found no customer with the given id"
}

Get

Retrieve a customer using the Grain customer id.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The UUID of the customer

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "companyName": "Ollivander's Wand Shop",
  • "companyAddress": "12 Diagon Alley",
  • "companyCity": "London",
  • "companyState": "London",
  • "companyCountry": "GB",
  • "contactEmail": "garrick@ollivanders.co.uk",
  • "contactFullName": "Garrick Ollivander",
  • "contactPhoneNumber": "+12125551234",
  • "companyTaxId": "123-45-6789",
  • "externalCustomerId": "630231b3ae0d7e9e5097ad35",
  • "status": "Pending",
  • "extraFields": {
    }
}

Delete

Delete a customer using the Grain customer id.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The UUID of the customer

Responses

Response samples

Content type
application/json
{
  • "message": "found no customer with the given id"
}

Transactions

Transaction objects represent the inventory. They represent a transaction performed by the customers of your business.
If the transaction contains a foreign currency exposure, it can also be hedged (using the quote endpoint followed by the accept endpoint while specifying the transactionId)

List

List all transactions for the given customer ID on the Grain platform.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The customer ID on the Grain platform.

query Parameters
from_currency
string

Return transactions with this "from currency" only.

to_currency
string

Return transactions with this "to currency" only.

page
number <double> (Page) >= 1

page number indicating which set of items to return

per_page
number <double> (PerPage) [ 1 .. 100 ]

The number of items in a page

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "pagination": {
    }
}

Create

Create a transaction with Grain, based on a transaction performed by a customer on your platform.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The id of the customer within the Grain platform.

Request Body schema: application/json
required

The payload required in order to create a transaction

fromCurrency
required
string

The currency in which the transaction should be paid at by your customer.

toCurrency
required
string

The currency in which the inventory item is listed at on your platform.

toCurrencyAmount
required
number <double>

The amount the transaction is listed in, denoted in toCurrency.

issuedAt
required
string <YYYY-MM-DD>

The date in which the transaction was created, denoted in YYYY-MM-DD ISO 8601 format.

dueAt
required
string <YYYY-MM-DD>

The date in which the transaction will be paid for, denoted in YYYY-MM-DD ISO 8601 format. Make sure dueAt date is after issuedAt date.

externalTransactionId
required
string

The transaction id, as identified within your system.

extraFields
object (ExtraFieldsParam)

Additional fields that provide further details about the transaction. These fields should be specified as a valid JSON object.

Responses

Request samples

Content type
application/json
{
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": "1560",
  • "issuedAt": "2023-01-18",
  • "dueAt": "2023-02-23",
  • "externalTransactionId": "780231b3ae0d7e9e5097nd89",
  • "extraFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get

Retrieve a specific transaction by its id.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The id of the customer within the Grain platform.

transactionId
required
string <uuid> (UUID)

The id of the transaction within the Grain platform.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": "1560",
  • "issuedAt": "2023-04-15",
  • "dueAt": "2023-04-15",
  • "cancelledAt": "2023-04-15",
  • "paidAt": "2023-04-15",
  • "externalCustomerId": "630231b3ae0d7e9e5097ad35",
  • "fromCurrencyIssuedAmount": "32161.8",
  • "fromCurrencyCurrentAmount": "32161.8",
  • "fromCurrencyPaidAmount": "null",
  • "hedgeIds": [
    ],
  • "externalTransactionId": "780231b3ae0d7e9e5097nd89"
}

Delete

Delete a specific transaction by its id.
This endpoint is used to delete data which was never actually bought on your platform but still reported to Grain.
For notifying Grain a transaction has been cancelled on your platform, see the transaction cancelled endpoint.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The id of the customer within the Grain platform.

transactionId
required
string <uuid> (UUID)

The id of the transaction within the Grain platform.

Responses

Response samples

Content type
application/json
{
  • "message": "found no transaction with the given id"
}

Paid

Notify grain of a transaction that has been cancelled after it was purchased on your platform.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The id of the customer within the Grain platform.

transactionId
required
string <uuid> (UUID)

The id of the transaction within the Grain platform.

Responses

Response samples

Content type
application/json
{
  • "hedgeIds": [
    ],
  • "transactionId": "4d78ac65-2c3f-47e2-8bf3-3f76124e9d27"
}

UpdateExternalTransactionId

Update an external transaction id of an existing transaction.

Authorizations:
api-key
path Parameters
customerId
required
string <uuid> (UUID)

The id of the customer within the Grain platform.

transactionId
required
string <uuid> (UUID)

The id of the transaction within the Grain platform.

Request Body schema: application/json
required

The payload required in order to update an external transaction id of transaction

externalTransactionId
required
string

The transaction id, as identified within your system.

Responses

Request samples

Content type
application/json
{
  • "externalTransactionId": "780231b3ae0d7e9e5097nd89"
}

Response samples

Content type
application/json
{
  • "hedgeIds": [
    ],
  • "transactionId": "4d78ac65-2c3f-47e2-8bf3-3f76124e9d27"
}

Hedges

Hedge objects represent transactions which are currently hedged.

Quote

Generates a quote for a new hedge attached to the customer matching the customerId path parameter.

Authorizations:
api-key
path Parameters
customerId
required
string

The id of the customer within the Grain platform.

header Parameters
X-Customer-IP
required
string <IPv4> (CustomerIP)

The IPv4 address of the browser from which the customer contacts your platform.
example: 192.158.1.38

Request Body schema: application/json
required

The payload required in order to ask for a hedge quote

fromCurrency
required
string

The currency in which the transaction should be paid at by your customer.

toCurrency
required
string

The currency in which the inventory item is listed at on your platform.

toCurrencyAmount
number <double>

The amount of toCurrency to hedge, using this amount and the hedge rate will determine the fromCurrency amount of the hedge.

endAt
required
string <YYYY-MM-DD> (GrainDateFormat)

The date format accepted by Grain's API. We accept dash separated ISO-8601 date-only strings.

Responses

Request samples

Content type
application/json
{
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": "1560",
  • "endAt": "2023-04-15"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "quote": "20.6165",
  • "validUntilTs": "1659625098",
  • "endAt": "2023-04-15",
  • "initialCollateralPercentage": "5",
  • "toCurrencyAmount": "1560",
  • "fromCurrencyAmount": "32161.8"
}

Accept

Accept a hedge quote, originated from quote request

Authorizations:
api-key
path Parameters
customerId
required
string

The id of the customer within the Grain platform.

header Parameters
X-Customer-IP
required
string <IPv4> (CustomerIP)

The IPv4 address of the browser from which the customer contacts your platform.
example: 192.158.1.38

Request Body schema: application/json
required

The payload required in order to accept a hedge

hedgeProposalId
required
string

The id of the hedge proposal to accept.

transactionId
string

The id of the transaction within the Grain platform. If not supplied, this hedge will be created without a transaction.

endAt
string <YYYY-MM-DD> (GrainDateFormat)

The date format accepted by Grain's API. We accept dash separated ISO-8601 date-only strings.

toCurrencyAmount
number <double>

The amount to hedge in the toCurrency, if amount was not specified on quote, it should be specified on Accept. This value is rounded up to two decimal places to ensure precision in the hedging process. For example, an input of 3052.1124 will be rounded to 3052.12.

externalTransactionId
string

The transaction id, as identified within your system - required only when the transactionId within the Grain platform is not provided.

extraFields
object (ExtraFieldsParam)

Additional fields that provide further details about the transaction. These fields should be specified as a valid JSON object.

Responses

Request samples

Content type
application/json
{
  • "hedgeProposalId": "8173b9a7-ee61-413e-b9e3-7c04b2a067c5",
  • "transactionId": "4d78ac65-2c3f-47e2-8bf3-3f76124e9d27",
  • "endAt": "2023-04-15",
  • "toCurrencyAmount": "1560",
  • "externalTransactionId": "780231b3ae0d7e9e5097nd89",
  • "extraFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

AcceptOfflineQuote

Accept a hedge quote, originated from the offline rates request

Authorizations:
api-key
path Parameters
customerId
required
string

The id of the customer within the Grain platform.

header Parameters
X-Customer-IP
required
string <IPv4> (CustomerIP)

The IPv4 address of the browser from which the customer contacts your platform.
example: 192.158.1.38

Request Body schema: application/json
required

The payload required in order to accept an offline quote hedge

revision
required
number <double>

The id of the revision that defines the accepted rate for the currency-pair and tenor.

fromCurrency
required
string

The currency in which the transaction should be paid at by your customer.

toCurrency
required
string

the currency you want to buy.

toCurrencyAmount
required
number <double>

The amount to hedge in the toCurrency.

endAt
required
string <YYYY-MM-DD> (GrainDateFormat)

The date format accepted by Grain's API. We accept dash separated ISO-8601 date-only strings.

rate
required
number <double>

Represents the exchange rate according to the offline map of currency pairs to tenor object.

The calculation of the tenor is based on the difference in calendar days between the 'tenorCalculationDate' and the 'endAt' date:

  • If the number of calendar days from 'tenorCalculationDate' to endAt is less than or equal to 7, the tenor is 7 days.
  • If the number of calendar days from 'tenorCalculationDate' to endAt is greater than 7 and less than or equal to 14, the tenor is 14 days.
  • If the number of calendar days from 'tenorCalculationDate' to endAt is greater than 14 and less than or equal to 30, the tenor is 30 days.
  • If the number of calendar days from 'tenorCalculationDate' to endAt is greater than 30 and less than or equal to 60, the tenor is 60 days.
  • ...
  • If the number of calendar days from 'tenorCalculationDate' to endAt is greater than 330 and less than or equal to 360, the tenor is 360 days.

When counting the difference in calendar days, every day is counted as one regardless of the duration of the day. This means that the calculation includes all days: weekends, holidays, and weekdays alike.

For example, if the 'endAt' date is 2023-12-16 and the 'tenorCalculationDate' is 2024-12-15, the result is 1 calendar day.

To calculate the difference in calendar days accurately, we recommend using a date manipulation library, such as date-fns and its differenceInCalendarDays function, or a similar feature provided by other date libraries.

externalTransactionId
string

Optional The transaction id, as identified within your system.

extraFields
object (ExtraFieldsParam)

Additional fields that provide further details about the transaction. These fields should be specified as a valid JSON object.

Responses

Request samples

Content type
application/json
{
  • "revision": 156,
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": 100000,
  • "endAt": "2023-04-15",
  • "rate": 20.616512,
  • "externalTransactionId": "780231b3ae0d7e9e5097nd89",
  • "extraFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

Get

Retrieve a specific hedge by its id.

Authorizations:
api-key
path Parameters
customerId
required
string

The id of the customer within the Grain platform.

hedgeId
required
string

The id of the hedge within the Grain platform.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "status": "Active",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "externalCustomerId": "630231b3ae0d7e9e5097ad35",
  • "toCurrencyAmount": "1560",
  • "fromCurrencyAmount": "32161.8",
  • "quote": "20.6165",
  • "acceptedAtTs": "1659625088",
  • "issuedAt": "2023-04-15",
  • "endAt": "2023-04-15",
  • "cancelledAt": "2023-02-23",
  • "fundsReceivedAt": "2023-02-23",
  • "completedAt": "2023-02-23",
  • "completedAtTs": "1659625090",
  • "overdueAt": "2023-04-15",
  • "settlementAt": "2023-04-15",
  • "settlementType": "collection"
}

Cancel

Cancel an existing hedge.

Authorizations:
api-key
path Parameters
customerId
required
string

The id of the customer within the Grain platform.

hedgeId
required
string

The id of the hedge within the Grain platform.

header Parameters
X-Customer-IP
required
string <IPv4> (CustomerIP)

The IPv4 address of the browser from which the customer contacts your platform.
example: 192.158.1.38

Request Body schema: application/json
required
reason
string

Description of the reason the hedge was canceled.

Responses

Request samples

Content type
application/json
{
  • "reason": "Mize"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

List

List all hedges for the given customer ID.

Authorizations:
api-key
path Parameters
customerId
required
string

The id of the customer within the Grain platform.

query Parameters
page
number <double> (Page) >= 1

page number indicating which set of items to return

per_page
number <double> (PerPage) [ 1 .. 100 ]

The number of items in a page

Responses

Response samples

Content type
application/json
{
  • "hedges": [
    ],
  • "pagination": {
    }
}

GetOfflineRates

Retrieves the latest rates for selected currency paris for offline use, using the Grain Partner ID.

Authorizations:
api-key
query Parameters
pairs
string

Optional query parameter specifying currency pairs. Multiple pairs can be provided as a comma-separated list. Please encode the query param beforehand. For example, ?pairs=EURUSD%2CGBPEUR represents ?pairs=EURUSD,GBPEUR

Responses

Response samples

Content type
application/json
{
  • "tenorCalculationDate": "2023-12-21",
  • "validUntilTs": 1703770471,
  • "rates": {
    },
  • "revision": 156
}

Spots

Spot objects represent currency exchange on a specific date

Quote

Generates a quote for a new spot, for current organization.

Authorizations:
api-key
header Parameters
X-Customer-IP
required
string <IPv4> (CustomerIP)

The IPv4 address of the browser from which the customer contacts your platform.
example: 192.158.1.38

Request Body schema: application/json
required

The payload required in order to ask for a spot quote

fromCurrency
required
string

The currency in which the transaction should be paid at by your customer.

toCurrency
required
string

The currency in which the inventory item is listed at on your platform.

toCurrencyAmount
number <double>

The amount of toCurrency to hedge, using this amount and the hedge rate will determine the fromCurrency amount of the hedge.

Responses

Request samples

Content type
application/json
{
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": "1560"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": "1560",
  • "fromCurrencyAmount": "32161.8",
  • "quote": "20.6165",
  • "validUntilTs": "1659625098"
}

Accept

Accept a spot quote, originated from a quote requested

Authorizations:
api-key
header Parameters
X-Customer-IP
required
string <IPv4> (CustomerIP)

The IPv4 address of the browser from which the customer contacts your platform.
example: 192.158.1.38

Request Body schema: application/json
required

The payload required in order to accept a spot

spotProposalId
required
string

The id of the spot proposal to accept.

toCurrencyAmount
number <double>

the amount to transfer in the toCurrency. If amount was not specified on quote, it should be specified on Accept.

extraFields
object (ExtraFieldsParam)

Additional fields that provide further details about the transaction. These fields should be specified as a valid JSON object.

Responses

Request samples

Content type
application/json
{
  • "spotProposalId": "8173b9a7-ee61-413e-b9e3-7c04b2a067c5",
  • "toCurrencyAmount": "1560",
  • "extraFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get

Retrieve a specific spot by its id.

Authorizations:
api-key
path Parameters
spotId
required
string

The id of the spot within the Grain platform.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "fromCurrency": "MXN",
  • "toCurrency": "USD",
  • "toCurrencyAmount": "1560",
  • "fromCurrencyAmount": "32161.8",
  • "quote": "20.6165",
  • "acceptedAtTs": "1659625088",
  • "issuedAt": "2023-04-15",
  • "completedAt": "2023-02-23"
}

List

List all spots for the given organization

Authorizations:
api-key
query Parameters
page
number <double> (Page) >= 1

page number indicating which set of items to return

per_page
number <double> (PerPage) [ 1 .. 100 ]

The number of items in a page

Responses

Response samples

Content type
application/json
{
  • "spots": [
    ],
  • "pagination": {
    }
}