Enterprise: net a multi-entity group

A group that both exports and imports usually holds surplus duty credit in one entity and duty demand in another. Selling the surplus on the open market and then buying credit back for the importing entity pays the spread twice. Netting removes that: internal surplus covers internal demand first, and only the true group-level residual reaches the market.

All calls below use the base URL and header from Authentication: export BASE_URL=https://api.scripxhq.com and X-ScripX-Key: $SCRIPX_KEY. Run the whole flow in the sandbox first with a scripx_test_… key.

1. Register every entity in the group

Each company in the group is its own firm, keyed by its own IEC, registered and verified individually. A firm registers as the side it trades, exporter or importer.

curl -X POST "$BASE_URL/v1/firms" \
  -H "X-ScripX-Key: $SCRIPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iec": "0512345678", "name": "Acme Textiles", "role": "exporter"}'

2. Read the group book

GET /v1/group/positions returns your book aggregated by company and scheme, already shaped the way the netting plan expects it.

curl "$BASE_URL/v1/group/positions" \
  -H "X-ScripX-Key: $SCRIPX_KEY"

{
  "party_iec": "0512345678",
  "positions": [
    {"iec": "0512345678", "scheme": "RODTEP", "net_paise": 100000000},
    {"iec": "0587654321", "scheme": "RODTEP", "net_paise": -60000000}
  ]
}

Positive net_paise is surplus credit; negative is duty demand.

3. Compute the netting plan

Feed those positions to POST /v1/group/net-plan. It returns the minimal set of internal transfers that squares the group, plus the residual left over.

curl -X POST "$BASE_URL/v1/group/net-plan" \
  -H "X-ScripX-Key: $SCRIPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"positions": [
        {"iec": "0512345678", "scheme": "RODTEP", "net_paise": 100000000},
        {"iec": "0587654321", "scheme": "RODTEP", "net_paise": -60000000}
      ]}'

{
  "summary": {"internal_paise": 60000000, "residual_paise": 40000000},
  "transfers": [
    {"from_iec": "0512345678", "to_iec": "0587654321", "scheme": "RODTEP", "amount_paise": 60000000}
  ]
}

The plan is a computation. It moves nothing and commits you to nothing.

4. Book each internal transfer

Execute each transfer in the plan as an intra-group cross with kind: "intra_group". Price it first so both legs are known before you commit.

curl -X POST "$BASE_URL/v1/cross" \
  -H "X-ScripX-Key: $SCRIPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seller_iec": "0512345678", "buyer_iec": "0587654321", "scheme": "RODTEP",
       "amount_paise": 60000000, "buy_price_bps": 9700, "sell_price_bps": 9700}'

A prepared cross never settles by itself. Settle funds it and confirm releases it, as two separate deliberate calls.

5. Take the residual to market

Whatever the plan reports as residual_paise is the group’s real market exposure. Trade it as an ordinary order on the side the residual falls, with a price floor or ceiling.

curl -X POST "$BASE_URL/v1/orders" \
  -H "X-ScripX-Key: $SCRIPX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-group-residual-2026-07" \
  -d '{"side": "sell", "scheme": "RODTEP", "amount_paise": 40000000, "min_pct_bps": 9600}'

6. Reconcile across the whole group

Statements itemise the period across every entity on your key.
The audit export is hash-chained and verifiable offline, covering internal transfers and market trades alike.
Each entity keeps its own expiry_date per credit, so watch validity before parking surplus inside the group.

​1. Register every entity in the group

​2. Read the group book

​3. Compute the netting plan

​4. Book each internal transfer

​5. Take the residual to market

​6. Reconcile across the whole group

​Related

1. Register every entity in the group

2. Read the group book

3. Compute the netting plan

4. Book each internal transfer

5. Take the residual to market

6. Reconcile across the whole group

Related