feat(swap): expose execution report fields in order get response

Replace top-level filled_input_amount/filled_output_amount with the
report object returned when state=30 and status=successful. Document
all report fields (amounts, tokens, decimals, price, gas) and update
order polling, post-swap receipt template, and cooking status polling
to reference report.input_amount / report.output_amount.

Closes GMGNAI/gmgn-skills#34

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
David Lau
2026-04-08 20:40:53 +08:00
co-authored by Claude Sonnet 4.6
parent 31fababfd8
commit 48a06cd9b4
2 changed files with 39 additions and 18 deletions
+1 -1
View File
@@ -167,7 +167,7 @@ Token creation is **asynchronous**. If the initial `cooking create` response sho
```bash
gmgn-cli order get --chain <chain> --order-id <order_id>
```
2. The new token's contract / mint address is in the **`output_token`** field of the `order get` response — it is NOT returned by `cooking create` directly.
2. The new token's contract / mint address is in the **`report.output_token`** field of the `order get` response (only present when `state = 30` and `status = "successful"`) — it is NOT returned by `cooking create` directly.
3. Stop polling once `status` is `confirmed`, `failed`, or `expired`.
4. On `confirmed`: display `output_token` as the token address and include the block explorer link.
5. On `failed` / `expired`: report the `error_status` and do not retry automatically.
+38 -17
View File
@@ -30,7 +30,7 @@ Use the `gmgn-cli` tool to submit a token swap or query an existing order. `GMGN
- **`order_id` / `status`** — After submitting a swap, the response includes an `order_id`. Use `order get --order-id` to poll for final status. Possible values: `pending``processed``confirmed` (success) or `failed` / `expired`. Do not report success until status is `confirmed`.
- **`filled_input_amount` / `filled_output_amount`** — Actual amounts consumed/received, in smallest unit. Convert to human-readable using token decimals before displaying to the user.
- **`report.input_amount` / `report.output_amount`** — Actual amounts consumed/received, in smallest unit. Only present when `state = 30` and `status = "successful"`. Convert to human-readable using `report.input_token_decimals` / `report.output_token_decimals` before displaying to the user.
## Financial Risk Notice
@@ -273,20 +273,41 @@ gmgn-cli swap \
> `buy_amount`: each take-profit sells 50% of the **original** bought amount. Stop-loss sells 100% of the original bought amount.
## `swap` Response Fields
## `swap` / `order get` Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `order_id` | string | Order ID for follow-up queries |
| `hash` | string | Transaction hash |
| `status` | string | Order status: `pending` / `processed` / `confirmed` / `failed` / `expired` |
| `error_code` | string | Error code on failure |
| `error_status` | string | Error description on failure |
| `input_token` | string | Input token contract address |
| `output_token` | string | Output token contract address |
| `filled_input_amount` | string | Actual input consumed (smallest unit); empty if not filled |
| `filled_output_amount` | string | Actual output received (smallest unit); empty if not filled |
| Field | Type | Description |
| ------------------- | ------ | ---- |
| `order_id` | string | Order ID for follow-up queries |
| `hash` | string | Transaction hash |
| `status` | string | Order status: `pending` / `processed` / `confirmed` / `failed` / `expired` |
| `error_code` | string | Error code on failure |
| `error_status` | string | Error description on failure |
| `strategy_order_id` | string | Strategy order ID; only present when `--condition-orders` was passed and strategy creation succeeded (best-effort) |
| `report` | object | Execution report; only present when `state = 30` and `status = "successful"`. See Report Fields below. |
### Report Fields (present only when `status = "successful"`)
| Field | Type | Description |
| ----------------------- | ------- | ---- |
| `input_token` | string | Input token contract address |
| `input_token_decimals` | integer | Input token decimal places |
| `swap_mode` | string | Swap mode: `ExactIn` / `ExactOut` |
| `input_amount` | string | Actual input consumed (smallest unit) |
| `output_token` | string | Output token contract address |
| `output_token_decimals` | integer | Output token decimal places |
| `output_amount` | string | Actual output received (smallest unit) |
| `quote_token` | string | Quote token contract address |
| `quote_decimals` | integer | Quote token decimal places |
| `quote_amount` | string | Quote amount (smallest unit) |
| `base_token` | string | Base token contract address |
| `base_decimals` | integer | Base token decimal places |
| `base_amount` | string | Base token amount (smallest unit) |
| `price` | string | Execution price (quote/base token) |
| `price_usd` | string | Execution price in USD |
| `height` | integer | Block height of execution |
| `order_height` | integer | Block height when order was placed |
| `gas_native` | string | Gas fee in native token |
| `gas_usd` | string | Gas fee in USD |
## Output Format
@@ -334,13 +355,13 @@ After a confirmed swap, display:
```
✅ Swap Confirmed
Spent: {filled_input_amount in human units} {input symbol}
Received: {filled_output_amount in human units} {output symbol}
Spent: {report.input_amount in human units} {input symbol}
Received: {report.output_amount in human units} {output symbol}
Tx: {explorer link for hash}
Order ID: {order_id}
```
Convert `filled_input_amount` and `filled_output_amount` from smallest unit using token decimals before displaying.
Convert `report.input_amount` and `report.output_amount` from smallest unit using `report.input_token_decimals` and `report.output_token_decimals` before displaying.
## `order strategy create` Parameters
@@ -502,7 +523,7 @@ For full token research before swapping, see [`docs/workflow-token-research.md`]
- **Percentage sell restriction** — `--percent` is ONLY valid when `input_token` is NOT a currency. Do NOT use `--percent` when `input_token` is SOL/BNB/ETH (native) or USDC. This includes: "sell 50% of my SOL", "use 30% of my BNB to buy X", "spend 50% of my USDC on X" — all unsupported. Explain the restriction to the user and ask for an explicit absolute amount instead.
- **Chain-wallet compatibility** — SOL addresses are incompatible with EVM chains (bsc/base). Warn the user and abort if the address format does not match the chain.
- **Credential sensitivity** — `GMGN_API_KEY` and `GMGN_PRIVATE_KEY` can directly execute trades on the linked wallet. Never log, display, or expose these values.
- **Order polling** — After a swap, if `status` is not yet `confirmed` / `failed` / `expired`, poll with `order get` up to 3 times at 5-second intervals before reporting a timeout. Once confirmed, display the trade result using `filled_input_amount` and `filled_output_amount` (convert from smallest unit using token decimals), e.g. "Spent 0.1 SOL → received 98.5 USDC" or "Sold 1000 TOKEN → received 0.08 SOL".
- **Order polling** — After a swap, if `status` is not yet `confirmed` / `failed` / `expired`, poll with `order get` up to 3 times at 5-second intervals before reporting a timeout. Once confirmed, display the trade result using `report.input_amount` and `report.output_amount` (convert from smallest unit using `report.input_token_decimals` / `report.output_token_decimals`), e.g. "Spent 0.1 SOL → received 98.5 USDC" or "Sold 1000 TOKEN → received 0.08 SOL".
- **Block explorer links** — After a successful swap, display a clickable explorer link for the returned `hash`:
| Chain | Explorer |