> ## Documentation Index
> Fetch the complete documentation index at: https://runelite.zip/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading

> Grand Exchange pipelines, player trades, shop purchases, and item price reads.

Three surfaces cover commerce: `GrandExchangeActions` for GE offers, `TradeActions` for player trades, and `ShopActions` for NPC shops. Price reads come from the SDK market APIs.

## Grand Exchange

`GrandExchangeActions` (`com.n3plugins.Api.actions`) manages independent GE operations. Every acting method returns `InteractionResult`, and offer construction returns `TaskPipeline` steps that route through the shared pacer.

| Method                                            | Returns             | Behavior                                                                                                               |
| ------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `openNearest()`                                   | `InteractionResult` | Walks to and opens the nearest Grand Exchange                                                                          |
| `isOpen()`                                        | `boolean`           | Interface state                                                                                                        |
| `collectAll()`                                    | `InteractionResult` | Collects all completed offers                                                                                          |
| `collectToBank()`                                 | `InteractionResult` | Collects completed offers to the bank                                                                                  |
| `cancelOffer(int slot)`                           | `InteractionResult` | Cancels a one-based offer slot                                                                                         |
| `close()`                                         | `InteractionResult` | Closes the open GE interface                                                                                           |
| `isPriceWarningVisible()`                         | `boolean`           | Whether a price discrepancy warning modal is open                                                                      |
| `handlePriceWarning()`                            | `boolean`           | Confirms and dismisses a visible price warning                                                                         |
| `createBuyPipeline(itemId, quantity, priceEach)`  | `TaskPipeline`      | Opens a free slot, sets item, price, quantity, confirms, handles price warnings, and waits for the submitted buy offer |
| `createSellPipeline(itemId, quantity, priceEach)` | `TaskPipeline`      | Same flow for a sell offer                                                                                             |

```java theme={null}
if (!GrandExchangeActions.isOpen()) {
    GrandExchangeActions.openNearest();
}
GrandExchangeActions.collectAll();
GrandExchangeActions.close();
```

The buy and sell pipelines cover the mechanical offer flow. Pricing policy, buy-limit decisions, retry rules, budget reservation, and pending-offer accounting stay with the caller. The GE Buyer plugin is the reference consumer of the buy pipeline.

<Warning>
  Treat a queued `SUCCESS` from `close()` as dispatch, not proof the interface closed. The close path searches the visible interface tree for a widget exposing `Close` and fails with `WIDGET_NOT_FOUND` rather than sending a guessed child packet, but you should still observe the interface state on a later tick.
</Warning>

`openNearest()` and `collectAll()` check the pacer before queuing and return `PACED` while the gate is closed, so a per-tick retry loop lands the action once the pacer clears. Calls made while the GE is closed return a non-success status instead of throwing.

## Player trades

`TradeActions` writes on the two-screen trade interface:

| Method                                          | Behavior                                                                      |
| ----------------------------------------------- | ----------------------------------------------------------------------------- |
| `accept()`                                      | Accepts whichever screen is currently open                                    |
| `acceptFirstScreen()`                           | Accept on the offer screen (group 335)                                        |
| `acceptSecondScreen()`                          | Accept on the confirm screen (group 334)                                      |
| `decline()`                                     | Declines whichever screen is open                                             |
| `declineFirstScreen()`, `declineSecondScreen()` | Explicit per-screen declines                                                  |
| `offer(itemId, quantity)`                       | Finds the item in inventory and offers it; `TRADE_ITEM_NOT_FOUND` when absent |

```java theme={null}
InteractionResult result = TradeActions.offer(ItemID.COINS_995, 1000);
if (result.failed() && result.getStatus() != InteractionStatus.PACED) {
    log.debug("Offer failed: {}", result.getMessage());
}
```

All methods return `TRADE_NOT_OPEN` when neither trade screen is visible, and the pacer gates every write. Inspect screen state, acceptance state, and either side's offer through `TradeQuery`, and re-validate the other player's offer on the confirmation screen before `acceptSecondScreen()`.

## Shops

`ShopActions` provides paced, result-aware purchase dispatches for NPC shops. Run buy methods only while the shop interface is open; a blocked action returns `PACED` for a next-tick retry.

| Method                     | Action queued |
| -------------------------- | ------------- |
| `buyOne(itemId or name)`   | `Buy-1`       |
| `buyFive(itemId or name)`  | `Buy-5`       |
| `buyTen(itemId or name)`   | `Buy-10`      |
| `buyFifty(itemId or name)` | `Buy-50`      |

Name overloads are case-insensitive and match the tag-stripped display name. Stock reads: `isOpen()`, `getStock(itemId)` (0 when absent or closed), and `getItems()` for the visible stock list.

```java theme={null}
if (!ShopActions.isOpen()) {
    return; // open the shop through NPC interaction first
}

int stock = ShopActions.getStock(560);
if (stock > 10) {
    ShopActions.buyTen(560);
}
```

<Warning>
  A successful buy dispatch means the packet queued, not that the server processed the purchase or that coins were sufficient. Track inventory container updates through the event layer to confirm the transaction.
</Warning>

## Item info and prices

The `sdk.items` package reads item metadata and prices without dispatching anything:

* `PricesApi` returns current price quotes for an item.
* `ItemInfo` exposes name and examine metadata.
* `WikiMarketClient` fetches market data, and `MarketPrice` models a quote for analysis code such as `AlchemyCandidateSelector`.

Use these reads to choose or explain an action, then dispatch through the action classes above. The [events and data playbook](/guides/events-data) covers the query helpers that pair with these surfaces.