> ## Documentation Index > Fetch the complete documentation index at: https://docs.grainfinance.co/llms.txt > Use this file to discover all available pages before exploring further. # List Hedges > Retrieves all hedges associated with the given customer. ## OpenAPI ````yaml GET /customers/{customerId}/hedges openapi: 3.1.0 info: title: Grain API version: 1.0.0 description: >- Grain's API provides a comprehensive set of endpoints for managing hedging, spot transactions, pricing, and fund movements - enabling seamless integration of FX workflows into your platform. Each API call follows REST conventions, uses secure authentication, and returns standardized responses for consistency across environments. license: name: Creative Commons Attribution 3.0 contact: name: Grain Finance url: https://docs.grainfinance.co email: support@grainfinance.co termsOfService: https://grainfinance.co/terms-of-service/ x-apiClientRegistration: url: https://grainfinance.co/partners servers: - url: https://api.grainfinance.co/v1 description: Grain API security: [] tags: - name: Hedges description: >- Hedge objects represent transactions that lock exchange rates for future dates. A single hedge locks an exchange rate for a future transaction between two currencies. - name: Dual Hedges description: >- A dual hedge mitigates FX risk by automatically generating two linked hedge legs - a customer leg and a supplier leg - both routed through the customer's functional currency. This structure reduces exposure to currency fluctuations for both cash flow and accounting purposes, while allowing independent tracking and reporting of each hedge leg. - name: Customers description: >- Customer objects represent your end customers on the Grain platform. A customer must be created before a hedge or spot transaction can be initiated. - name: Pricing description: >- Pricing endpoints provide access to FX rates for currency pairs that are not being hedged. These endpoints can be used for live rate display or bulk retrieval to support high-volume quoting workflows. - name: Spots description: >- Spot objects represent currency conversions executed for immediate or near-term settlement. - name: Conversions description: >- Conversion objects represent currency conversions executed for immediate or near-term settlement. - name: Wallets description: Endpoints to view balances, manage funding, and perform transfers. paths: /customers/{customerId}/hedges: get: tags: - Hedges description: Retrieves all hedges associated with the given customer. operationId: List parameters: - description: The id of the customer within the Grain platform. in: path name: customerId required: true schema: type: string - description: page number indicating which set of items to return in: query name: page required: false schema: $ref: '#/components/schemas/Page' - description: The number of items in a page in: query name: per_page required: false schema: $ref: '#/components/schemas/PerPage' responses: '200': description: Hedges List for Customer content: application/json: schema: $ref: '#/components/schemas/ListHedgesResponseBody' '404': description: The request failed because the resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api-key: [] components: schemas: Page: type: number format: double description: The page indicating which set of items are returned minimum: 1 PerPage: type: number format: double description: number of items in a page minimum: 1 maximum: 100 ListHedgesResponseBody: description: A response containing a list of hedges matching the search criteria. properties: hedges: items: $ref: '#/components/schemas/CustomerHedge' type: array description: A list of hedges matching the search criteria. pagination: $ref: '#/components/schemas/PaginationResponse' required: - hedges - pagination type: object additionalProperties: false ErrorResponse: description: An API Error properties: message: type: string description: A short explanation of the error. example: Can't perform this action reason: type: string description: A detailed description of the reason for the failure. example: >- Supplied object is in *Cancelled* state, which prevents performing this action required: - message type: object additionalProperties: false CustomerHedge: anyOf: - $ref: '#/components/schemas/CollectionHedge' - $ref: '#/components/schemas/OffsetHedge' description: Hedge objects represent transactions which are currently hedged. PaginationResponse: description: Pagination parameters of the returned results. properties: page: $ref: '#/components/schemas/Page' perPage: $ref: '#/components/schemas/PerPage' totalResults: type: number format: double description: The total amount of results available required: - page - perPage - totalResults type: object additionalProperties: false CollectionHedge: properties: id: $ref: '#/components/schemas/UUID' description: The id of the hedge within the Grain platform. example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5 customerId: $ref: '#/components/schemas/UUID' description: The id of the customer within the Grain platform. example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e status: $ref: '#/components/schemas/HedgeStatus' description: The Status of the Hedge example: Active transactionId: $ref: '#/components/schemas/UUID' description: The id of the transaction within the Grain platform. example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27 externalTransactionId: type: string description: The transaction id as identified within your system. example: 780231b3ae0d7e9e5097nd89 fromCurrency: type: string description: >- The currency in which the transaction should be paid at by your customer. example: MXN toCurrency: type: string description: >- The currency in which the inventory item is listed at on your platform. example: USD externalCustomerId: type: string description: The id used to identify the customer within your platform example: 630231b3ae0d7e9e5097ad35 toCurrencyAmount: type: number format: double description: >- The amount to hedge in the toCurrency. If fromCurrencyAmount is provided, then toCurrencyAmount calculated as: `toCurrencyAmount = fromCurrencyAmount / quote` example: 1560 fromCurrencyAmount: type: number format: double description: >- The amount to hedge in the fromCurrency. If toCurrencyAmount is provided, then fromCurrencyAmount calculated as: `fromCurrencyAmount = toCurrencyAmount * quote` example: 32161.8 fixedSide: $ref: '#/components/schemas/DisplayFixedSide' description: >- Indicates which currency amount was fixed (specified) when creating the hedge. When `fixedSide` is `toCurrencyAmount`, the `toCurrencyAmount` was specified and `fromCurrencyAmount` was calculated. When `fixedSide` is `fromCurrencyAmount`, the `fromCurrencyAmount` was specified and `toCurrencyAmount` was calculated. example: toCurrencyAmount initialCollateralAmount: type: number format: double description: >- The initial collateral amount required for this hedge in the fromCurrency. Calculated as fromCurrencyAmount * initialCollateralPercentage. example: 1608.09 quote: type: number format: double description: The rate locked by this hedge. example: 20.6165 externalMarkupPct: type: - number - 'null' format: double description: >- The external markup percentage that should be added to this quote on top of Grain’s internal pricing. For example, a value of 1.0 represents a 1.0% additional markup. example: 1 acceptedAtTs: type: number format: double description: >- The unix timestamp in which the hedge offer was accepted (if it was). example: 1659625088 issuedAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge was issued, denoted in `YYYY-MM-DD` format. example: '2023-01-18' endAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format. example: '2023-02-23' updatedAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge was last modified, denoted in `YYYY-MM-DD` format. example: '2023-02-23' cancelledAt: description: >- The date in which the hedge was cancelled, denoted in `YYYY-MM-DD` format. example: '2023-02-23' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' initialCollateralReceivedAt: description: >- The date in which the initial collateral was received, denoted in `YYYY-MM-DD` format. Null if not yet received. example: '2023-01-20' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' fundsReceivedAt: description: >- The date in which the funds of the hedge arrived, afterwards the settlement occurs denoted in `YYYY-MM-DD` format. example: '2023-02-23' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' completedAt: description: >- The date in which the hedge was completed, denoted in `YYYY-MM-DD` format. example: '2023-02-23' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' completedAtTs: type: - number - 'null' format: double description: The unix timestamp in which the hedge was completed. example: 1659625090 overdueAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge will become overdue, denoted in `YYYY-MM-DD` format. example: '2023-02-23' settlementAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge begins settlement, denoted in `YYYY-MM-DD` format. example: '2023-02-23' settlementType: $ref: '#/components/schemas/DisplaySettlementType.Full' description: >- The method in which the hedge is being settled. If 'full' type is set, the total hedge amount should be sent to Grain prior to settlement adjustedMtmChangePct: type: - number - 'null' format: double description: >- The percentage change in the adjusted mark-to-market value since the previous valuation. A value of 1.0 represents a 1.0% change. A negative value indicates a potential margin call if the threshold has been exceeded. example: 1.25 adjustedMtmChangeTs: type: - number - 'null' format: double description: >- The timestamp at which the latest adjusted mark-to-market change was calculated. example: 1674057600 required: - id - customerId - status - transactionId - externalTransactionId - fromCurrency - toCurrency - externalCustomerId - toCurrencyAmount - fromCurrencyAmount - fixedSide - initialCollateralAmount - quote - externalMarkupPct - acceptedAtTs - issuedAt - endAt - updatedAt - cancelledAt - initialCollateralReceivedAt - fundsReceivedAt - completedAt - completedAtTs - overdueAt - settlementAt - settlementType - adjustedMtmChangePct - adjustedMtmChangeTs type: object additionalProperties: false OffsetHedge: properties: id: $ref: '#/components/schemas/UUID' description: The id of the hedge within the Grain platform. example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5 customerId: $ref: '#/components/schemas/UUID' description: The id of the customer within the Grain platform. example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e status: $ref: '#/components/schemas/HedgeStatus' description: The Status of the Hedge example: Active transactionId: $ref: '#/components/schemas/UUID' description: The id of the transaction within the Grain platform. example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27 externalTransactionId: type: string description: The transaction id as identified within your system. example: 780231b3ae0d7e9e5097nd89 fromCurrency: type: string description: >- The currency in which the transaction should be paid at by your customer. example: MXN toCurrency: type: string description: >- The currency in which the inventory item is listed at on your platform. example: USD externalCustomerId: type: string description: The id used to identify the customer within your platform example: 630231b3ae0d7e9e5097ad35 toCurrencyAmount: type: number format: double description: >- The amount to hedge in the toCurrency. If fromCurrencyAmount is provided, then toCurrencyAmount calculated as: `toCurrencyAmount = fromCurrencyAmount / quote` example: 1560 fromCurrencyAmount: type: number format: double description: >- The amount to hedge in the fromCurrency. If toCurrencyAmount is provided, then fromCurrencyAmount calculated as: `fromCurrencyAmount = toCurrencyAmount * quote` example: 32161.8 fixedSide: $ref: '#/components/schemas/DisplayFixedSide' description: >- Indicates which currency amount was fixed (specified) when creating the hedge. When `fixedSide` is `toCurrencyAmount`, the `toCurrencyAmount` was specified and `fromCurrencyAmount` was calculated. When `fixedSide` is `fromCurrencyAmount`, the `fromCurrencyAmount` was specified and `toCurrencyAmount` was calculated. example: toCurrencyAmount initialCollateralAmount: type: number format: double description: >- The initial collateral amount required for this hedge in the fromCurrency. Calculated as fromCurrencyAmount * initialCollateralPercentage. example: 1608.09 quote: type: number format: double description: The rate locked by this hedge. example: 20.6165 externalMarkupPct: type: - number - 'null' format: double description: >- The external markup percentage that should be added to this quote on top of Grain’s internal pricing. For example, a value of 1.0 represents a 1.0% additional markup. example: 1 acceptedAtTs: type: number format: double description: >- The unix timestamp in which the hedge offer was accepted (if it was). example: 1659625088 issuedAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge was issued, denoted in `YYYY-MM-DD` format. example: '2023-01-18' endAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format. example: '2023-02-23' updatedAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge was last modified, denoted in `YYYY-MM-DD` format. example: '2023-02-23' cancelledAt: description: >- The date in which the hedge was cancelled, denoted in `YYYY-MM-DD` format. example: '2023-02-23' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' initialCollateralReceivedAt: description: >- The date in which the initial collateral was received, denoted in `YYYY-MM-DD` format. Null if not yet received. example: '2023-01-20' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' fundsReceivedAt: description: >- The date in which the funds of the hedge arrived, afterwards the settlement occurs denoted in `YYYY-MM-DD` format. example: '2023-02-23' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' completedAt: description: >- The date in which the hedge was completed, denoted in `YYYY-MM-DD` format. example: '2023-02-23' oneOf: - $ref: '#/components/schemas/GrainDateFormat' - type: 'null' completedAtTs: type: - number - 'null' format: double description: The unix timestamp in which the hedge was completed. example: 1659625090 overdueAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge will become overdue, denoted in `YYYY-MM-DD` format. example: '2023-02-23' settlementAt: $ref: '#/components/schemas/GrainDateFormat' description: >- The date in which the hedge begins settlement, denoted in `YYYY-MM-DD` format. example: '2023-02-23' settlementType: $ref: '#/components/schemas/DisplaySettlementType.Offset' description: >- The method in which the hedge is being settled. If 'offset' type is set, only the difference between the locked rate and settlement rate is exchanged adjustedMtmChangePct: type: - number - 'null' format: double description: >- The percentage change in the adjusted mark-to-market value since the previous valuation. A value of 1.0 represents a 1.0% change. A negative value indicates a potential margin call if the threshold has been exceeded. example: 1.25 adjustedMtmChangeTs: type: - number - 'null' format: double description: >- The timestamp at which the latest adjusted mark-to-market change was calculated. example: 1674057600 settlementAmount: type: number format: double description: >- The total amount settled for the hedge. The amount can be positive or negative example: 10.99 settlementCurrency: type: string description: The currency in which the settlement was processed example: USD endDateQuote: type: number format: double description: The rate used to calculate the hedge settlement amount example: 20.9236 required: - id - customerId - status - transactionId - externalTransactionId - fromCurrency - toCurrency - externalCustomerId - toCurrencyAmount - fromCurrencyAmount - fixedSide - initialCollateralAmount - quote - externalMarkupPct - acceptedAtTs - issuedAt - endAt - updatedAt - cancelledAt - initialCollateralReceivedAt - fundsReceivedAt - completedAt - completedAtTs - overdueAt - settlementAt - settlementType - adjustedMtmChangePct - adjustedMtmChangeTs type: object additionalProperties: false UUID: type: string format: uuid description: |- Stringified UUIDv4. See [RFC 4112](https://tools.ietf.org/html/rfc4122) pattern: >- [0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12} HedgeStatus: enum: - Active - Cancelled - Completed - InProcess - Overdue type: string DisplayFixedSide: description: |- The fixed side as displayed in external APIs (camelCase format). Indicates which currency amount was specified when creating the hedge. enum: - toCurrencyAmount - fromCurrencyAmount type: string GrainDateFormat: type: string example: '2023-04-15' format: YYYY-MM-DD description: >- The date format accepted by Grain's API. We accept dash separated ISO-8601 date-only strings. pattern: \d{4}-\d{2}-\d{2} DisplaySettlementType.Full: enum: - full type: string DisplaySettlementType.Offset: enum: - offset type: string securitySchemes: api-key: type: http scheme: basic description: >- Basic authentication using the partner API keys from https://console.grainfinance.co/keys ````