Bid into an offering

{
  "amount": 5000000,
  "bid_price": 10.5,
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

{
  "amount": 5000000,
  "bid_rate": 19,
  "tranche": "retail",
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

{
  "status": "success",
  "message": "Commitment recorded. The funds are held until allotment.",
  "data": {
    "_id": "68f1c1a3e1b2c3d4e5f60615",
    "token": "68f1c2a4e1b2c3d4e5f60718",
    "amount": 5000000,
    "hold_amount": 5025000,
    "bid_rate": 19,
    "tranche": "retail",
    "status": "SUBMITTED"
  }
}

POST

api

token

{id}

commit

{
  "amount": 5000000,
  "bid_price": 10.5,
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

{
  "amount": 5000000,
  "bid_rate": 19,
  "tranche": "retail",
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

{
  "status": "success",
  "message": "Commitment recorded. The funds are held until allotment.",
  "data": {
    "_id": "68f1c1a3e1b2c3d4e5f60615",
    "token": "68f1c2a4e1b2c3d4e5f60718",
    "amount": 5000000,
    "hold_amount": 5025000,
    "bid_rate": 19,
    "tranche": "retail",
    "status": "SUBMITTED"
  }
}

Places a bid into an offering’s book. The funds are held on your organisation’s wallet — in offer_hold, its own bucket, distinct from escrow — for the whole offer period, and either buy units at allotment or are released back. You are the counterparty, exactly as you are on a buy. The customer object records which of your end users the bid was for; GetEquity never provisions an account for that person, so reconciling the position to them remains yours.

string

required

The id of the offering to bid into.

number

required

The cash being committed. Held on the wallet until allotment.

number

The highest price you will pay. Price-based offerings only. Mutually exclusive with bid_rate.

number

The lowest rate you will accept. Rate-based offerings — debt and fixed interest — only.

boolean

Bid at whatever the book settles at, naming no limit. Only where the offering allows it.

string

Required on a combined offering, refused on every other type. The tranche’s key, from the order book. See below.

object

Anything you want echoed back on the commitment.

object

name and email of the end user this bid belongs to.

{
  "amount": 5000000,
  "bid_price": 10.5,
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

{
  "amount": 5000000,
  "bid_rate": 19,
  "tranche": "retail",
  "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

{
  "status": "success",
  "message": "Commitment recorded. The funds are held until allotment.",
  "data": {
    "_id": "68f1c1a3e1b2c3d4e5f60615",
    "token": "68f1c2a4e1b2c3d4e5f60718",
    "amount": 5000000,
    "hold_amount": 5025000,
    "bid_rate": 19,
    "tranche": "retail",
    "status": "SUBMITTED"
  }
}

Offerings that have tranches

Some offerings are split into separate books called tranches — a commercial paper issued as retail and institutional slices, or as 90/180/270-day series. Each is priced and allotted against its own size, so they can clear at different levels. Read the offering’s tranches from the order book. If the array is present you must send tranche; if it is absent you must not.

"tranches": [
  { "key": "retail",        "name": "Retail",        "size": 40000000, "min_commitment": 100000 },
  { "key": "institutional", "name": "Institutional", "size": 60000000, "min_commitment": 50000000 }
]

Send the key, not the name. A tranche may set its own ticket size and its own audience (investors: ANY, user or organisation), and a bid outside either is refused. A bid cannot move between tranches afterwards — withdraw it and place a fresh one.

Price or rate?

Debt and fixed-interest offerings discover a rate; everything else discovers a price. Send bid_rate on the former and bid_price on the latter — never both. Check the offering’s investment_type before deciding which.

What a bid is checked against

The bounds come from the tranche where the offering has them, and from the offering otherwise.

Refusal	Meaning
`OFFERING_NOT_OPEN_ERROR`	The book is not open for bids.
`BID_BELOW_GUIDANCE_ERROR` / `BID_ABOVE_GUIDANCE_ERROR`	Outside an enforced range.
`BID_OFF_TICK_ERROR`	Not on the guidance step.
`BID_BEYOND_RESERVE_ERROR`	Past the worst level the issuer will accept.
`BID_LIMIT_REQUIRED_ERROR`	No limit named, and strike bids are not allowed here.
`STRIKE_BIDS_NOT_ALLOWED_ERROR`	This offering requires a limit on every bid.
`WALLET_INSUFFICIENT_BALANCE_ERROR`	Not enough to cover the bid and its fee.
`TRANCHE_REQUIRED_ERROR`	Combined offering, no tranche named.
`OFFERING_HAS_NO_TRANCHES_ERROR`	Tranche named on a single-book offering.
`TRANCHE_NOT_OPEN_ERROR`	The tranche is restricted to the other kind of holder.
`BELOW_TRANCHE_MINIMUM_ERROR` / `ABOVE_TRANCHE_MAXIMUM_ERROR`	Outside the tranche’s ticket size.

API Documentation

Investments API · Direct

Investments API · Managed

Credit API

Webhook

Bid into an offering

Offerings that have tranches

Price or rate?

What a bid is checked against

​Offerings that have tranches

​Price or rate?

​What a bid is checked against

Offerings that have tranches

Price or rate?

What a bid is checked against