MyGrainExchange

Trades

Read the trades your team is party to. Requires the trades.read scope and a token bound to a team via Login with MGX.

The counterparty stays null until both invoices on the trade are paid — the deal terms are visible, but not who the other party is, until settlement. See the counterparty object.

The trade model

  • Name
    id
    Type
    string
    Description
    Opaque trade id, e.g. trd_5Lp8.
  • Name
    side
    Type
    string
    Description
    buyer or seller, relative to your team.
  • Name
    status
    Type
    string
    Description
    Trade status.
  • Name
    commodity
    Type
    object
    Description
    slug and name.
  • Name
    quantity_mt
    Type
    number
    Description
    Quantity in tonnes.
  • Name
    price
    Type
    object
    Description
    amount, currency, unit.
  • Name
    counterparty
    Type
    object
    Description
    The other party to the trade. Null until both invoices are paid — see the counterparty object.
  • Name
    settled_at
    Type
    string
    Description
    When the trade settled.

The counterparty object

MGX's privacy rule is that neither side of a deal learns who the other is until the deal is done. The counterparty field on a trade, a bid, a received bid, and a cash bid offer all follow the same rule and share the same shape:

  • Before settlement the field is null. Not an empty object, not a placeholder — null. Read the deal terms; treat the identity as unknown.
  • Once both invoices on the trade are paid, the field becomes an object and settled_at is set. On a bid or offer, this means the trade it produced has settled.
  • The trade.settled webhook fires at exactly that moment. Re-fetch the trade to read the unmasked counterparty.
  • Name
    name
    Type
    string
    Description
    The counterparty's full name as registered on MGX. May be null if the account has no name on file.

Message threads use a richer party shape — label, company, is_elevator — because a verified elevator is named there even before settlement. See who is who.

Counterparty

{
  "id": "trd_5Lp8",
  "status": "paid",
  "counterparty": null,
  "settled_at": null
}
GET/v1/trades

List trades

Trades your team bought or sold.

  • Name
    status
    Type
    string
    Description
    Filter by status.
  • Name
    commodity
    Type
    string
    Description
    Filter by commodity.
  • Name
    from
    Type
    string
    Description
    Created on or after (ISO date).
  • Name
    to
    Type
    string
    Description
    Created on or before (ISO date).

Request

GET
/v1/trades
curl "https://api.mygrainexchange.com/v1/trades?status=paid" \
  -H "Authorization: Bearer {token}"
GET/v1/trades/:id

Get a trade

Retrieve one of your team's trades by id. Returns 404 if your team is not party to it.

Request

GET
/v1/trades/trd_5Lp8
curl https://api.mygrainexchange.com/v1/trades/trd_5Lp8 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "trd_5Lp8",
    "reference": "TRD-26G-0018",
    "side": "buyer",
    "status": "delivered",
    "commodity": { "slug": "canola", "name": "Canola" },
    "quantity_mt": 86.0,
    "price": { "amount": 308.0, "currency": "CAD", "unit": "MT" },
    "counterparty": { "name": "Dale Henderson" },
    "settled_at": "2026-07-22T15:04:11-06:00",
    "created_at": "2026-07-16T21:12:27-06:00"
  }
}

Was this page helpful?