Skip to content

feat(sdk): add limit order actions and run quote/v3 style steps - #1184

Open
pedromcunha-uneven wants to merge 4 commits into
mainfrom
pedro/dx-2060-limit-orders-sdk-actions-create-get-cancel
Open

pedromcunha-uneven wants to merge 4 commits into
mainfrom
pedro/dx-2060-limit-orders-sdk-actions-create-get-cancel

Conversation

@pedromcunha-uneven

Copy link
Copy Markdown
Collaborator

Summary

Adds SDK actions for the Orders API (limit orders) and lets executeSteps run quote/v3-style flat steps, which is the step format the Orders API returns. Order steps run through the same execution path as quote steps.

Changes and decisions to review

  • New actions in packages/sdk/src/actions/orders.ts, also available on client.actions: createOrder (POST /orders, optional idempotencyKey sent as Idempotency-Key), getOrders (GET /orders), signOrder (POST /orders/:orderId/signature), cancelOrder (POST /orders/:orderId/cancel) and executeOrder.
  • Wallet is optional. With a wallet, createOrder and cancelOrder run the order's steps and report progress through onProgress. Without one, they return the order so its steps can run later with executeOrder, for example to resume a pending order read with getOrders.
  • No order-specific runner. executeOrder hands the order's steps to executeSteps. It clones them first, as execute() does, so the caller's Order is not mutated (executeSteps writes referrer into post bodies). It then reads the order back with GET /orders?orderId=, because executeSteps does not surface the signature post's response.
  • signOrder sends the signature as the signature query param, the same way executeSteps posts signature steps, with a JSON {} body.
  • cancelOrder is a soft cancel unless onchain: true is passed; with onchain and a wallet, it sends the returned cancel transaction.
  • getOrders takes status as an array and sends it comma-separated.
  • executeSteps accepts flat steps (status, data and check on the step) as well as legacy items steps. Flat steps are converted to the items shape internally, so onProgress and the returned steps keep today's shape. A flat step without a requestId takes the response's top-level requestId, a new optional field on Execute.
  • Execute's step id union is unchanged. Only the new FlatExecuteStep input type includes the order step ids (cancel, withdraw). Widening Execute breaks assigning it to quote response types, as the UI does in isGasSponsored.
  • Order types are hand-written in types/Order.ts, because the Orders endpoints are not in the generated API types yet.
  • Two changesets (minor): the order actions, and flat step support in executeSteps.

Testing

  • packages/sdk: vitest run, 110 passed. New orders.test.ts covers create with approval and signature, create without a wallet, list params, soft cancel and onchain cancel. A new executeSteps test runs flat steps. Each new test fails when the behavior it covers is reverted.
  • tsc --noEmit passes for packages/sdk and packages/ui.
  • Ran the built SDK with a real viem wallet (local EIP-712 signing) against a local server implementing the Orders API endpoints: create, sign and open; list; error codes surfaced on APIError.rawError.errorCode; onchain cancel; resume with executeOrder; and signOrder directly.
  • Not covered: sending the approval and cancel transactions on a real chain (unit tests only).

Add createOrder, getOrders, signOrder, cancelOrder and executeOrder for the
Orders API, with Order types. executeSteps now also accepts flat steps that
carry status, data and check on the step, alongside legacy items steps, and
order steps run through it.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1cbc7-42ee-7072-956d-ef88023ffd1d
@vercel

vercel Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
relay-sdk-demo Ready Ready Preview Nov 14, 2026 3:34am UTC

Request Review

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @pedromcunha-uneven's task in 50s —— View job


Code Review: 2 issues found, both minor

  1. [NOTE] Error handling: executeOrder can return undefined typed as Order
    packages/sdk/src/actions/orders.ts:178: After the steps run, executeOrder reads the order back with getOrders({ orderId }) and returns orders[0] without checking it exists. If the read-back returns no orders (for example, the client's API key belongs to a different integrator than the order's, since GET /orders only lists orders for the key's integrator), createOrder, cancelOrder and executeOrder all resolve to undefined even though their return type is Promise<Order>. The caller then fails later on a property access instead of getting a clear error. Suggested fix: throw when orders[0] is missing, or fall back to the order that was passed in and say so in the JSDoc.

  2. [NOTE] Repo guideline: // ABOUTME: header missing
    packages/sdk/src/actions/orders.ts:1, packages/sdk/src/types/Order.ts:1, packages/sdk/src/actions/orders.test.ts:1: The review guidelines ask new files to start with a 2-line // ABOUTME: comment, and none of these three do. No existing file under packages/ uses this header either, so you may decide the rule doesn't apply in this repo.

Other things I checked that look correct:

  • normalizeSteps runs on every recursive call. Steps added by a signature post response are normalized too, and steps already in the items shape pass through unchanged.
  • The top-level requestId is copied onto flat steps, so extractDepositRequestId and the websocket setup still work for quote/v3 responses.
  • canBatchTransactions won't batch order steps: their terminal ids (authorize, cancel) aren't swap or deposit.
  • executeOrder clones order.steps before calling executeSteps, so the caller's Order isn't mutated when referrer is written into the post body. It also passes a fresh request object, so the signature param doesn't carry over between calls.
  • executeSteps still rethrows after setState(error), so errors reach callers of createOrder and cancelOrder.
  • getOrders leaves status out of the request when it is empty or undefined.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @pedromcunha-uneven's task in 30s —— View job


📝 Docs Drift Check — Confidence: LOW (below configured floor: medium)

What changed: The SDK adds five limit-order actions on client.actions: createOrder, getOrders, signOrder, cancelOrder and executeOrder. It also exports order types (Order, OrderStatus, CreateOrderBody, GetOrdersQuery, …). Separately, the step runner now accepts flat quote/v3-style steps and exports a FlatExecuteStep type.

Why I didn't draft: The docs have no public page for the Orders API: no endpoint reference, no feature guide, and no mention of limit orders. SDK action pages would be the first public description of the feature. Whether it has launched, and how it should be introduced (feature guide, then API reference, then SDK), can't be decided from this diff alone.

Pages likely affected:

  • references/relay-kit/sdk/actions/createOrder.mdx: new. Arguments order, idempotencyKey, wallet and onProgress. Describe what happens with and without a wallet.
  • references/relay-kit/sdk/actions/getOrders.mdx: new. Query filters, status given as an array, and pagination with continuation.
  • references/relay-kit/sdk/actions/cancelOrder.mdx: new. Soft cancel by default; with onchain: true, the Permit2 nonce is invalidated.
  • references/relay-kit/sdk/actions/executeOrder.mdx and signOrder.mdx: new, or folded into the createOrder page. This is a placement decision.
  • features/ page plus references/api/ endpoint stubs for /orders: these are probably needed first so the SDK pages have something to link to. This depends on the Orders endpoints being in the public OpenAPI spec.
  • docs.json: add the new SDK action pages to the SDK actions nav group.
  • Flat-step support in the step runner: no docs change needed. The step runner isn't documented on its own, and execute and onProgress behave the same as before.

Suggested next step: Open an issue or PR in relayprotocol/relay-docs by hand once the Orders API is public, starting with the feature guide and API reference pages. The fastFill SDK page fits the action pages' structure best. Do NOT use /publish-docs-pr, which would publish a low-confidence draft.

@greptile-apps

greptile-apps Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[High impact] The changes since the previous review appear safe to merge.

Summary

Adds order actions and lets executeSteps accept flat steps while keeping its existing progress format.

  • Apps can create, track, sign, and cancel limit orders through the SDK.
  • executeSteps runs flat quote and order steps through the shared runner.

Reviews (4) · Last reviewed commit: "refactor(sdk): split order actions into ..." · Reviewed by Greptile

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @pedromcunha-uneven's task in 25s —— View job


Code Review: No issues found.

I reviewed 10 files (+687/−3) for correctness, security, error handling and the repo guidelines.

Since the last review:

  • Fixed in 6e3265d: the read-back after running the steps used to return orders[0] without checking it. executeOrder now throws a clear error when the order isn't listed for the client's API key. A new test covers this: fails when the order is not listed after its steps run.
  • Unchanged: the three new files (orders.ts, Order.ts, orders.test.ts) still have no // ABOUTME: header. No file under packages/ uses that header, so I'm not counting it as an issue here.

Also checked, and these look correct:

  • Signature post URL and API key: executeOrder passes request = {}. executeSteps fills in request.baseURL = client.baseApiUrl (utils/executeSteps/index.ts:94) before signatureStep calls resolveApiUrl(request.baseURL!, …). The signature post therefore goes to the configured API, and the API key is attached the same way as in requestOrders.
  • Signature post response: it returns { order } with no top-level steps, so no steps get appended. The flow ends after the post, and then the order is read back.
  • Step normalization: normalizeSteps runs on every recursive pass. Steps already in the items shape pass through unchanged. Flat steps without a requestId get the response's top-level requestId, so status polling still finds the request (the new executeSteps test checks this).
  • getOrders status filter: an empty or missing status sends undefined, which axios leaves out of the query string.
  • Steps with nothing left to do: executeOrder returns early without calling the API.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @pedromcunha-uneven's task in 19s —— View job


📝 Docs Drift Check — Confidence: LOW (below configured floor: medium)

What changed: The SDK adds five limit-order actions on client.actions: createOrder, getOrders, signOrder, cancelOrder and executeOrder. It also exports order types such as Order, OrderStatus, CreateOrderBody and GetOrdersQuery. The latest commit makes executeOrder throw an error if, after its steps run, the order is not listed for the client's API key. Because createOrder and cancelOrder run through executeOrder when given a wallet, they now throw in that case too. Separately, the step runner now accepts flat quote/v3-style steps.

Why I didn't draft: The docs say nothing about limit orders or the Orders API yet: no endpoint reference, no feature guide and no mention of the feature. These SDK action pages would be its first public description, and this diff can't tell me whether it has launched or how it should be introduced.

Pages likely affected:

  • references/relay-kit/sdk/actions/createOrder.mdx: new page. It should cover the order, idempotencyKey, wallet and onProgress arguments, explain what happens with and without a wallet, and note the error thrown when the order isn't listed for the API key afterwards.
  • references/relay-kit/sdk/actions/getOrders.mdx: new page. It should cover the query filters, passing status as an array, and pagination with continuation.
  • references/relay-kit/sdk/actions/cancelOrder.mdx: new page. Cancelling is a soft cancel by default; with onchain: true it also sends an onchain cancel transaction.
  • references/relay-kit/sdk/actions/executeOrder.mdx and signOrder.mdx: new pages, or fold them into the createOrder page (a placement decision). executeOrder is for resuming pending orders. It reads the order back afterwards and throws if the order isn't listed for the API key.
  • A features/ page plus references/api/ pages for the /orders endpoints: these probably need to come first so the SDK pages have something to link to. They depend on the Orders endpoints being in the public OpenAPI spec.
  • docs.json: add the new action pages to the SDK actions navigation group.
  • Flat-step support in the step runner: no docs change needed. execute and onProgress keep their documented behavior.

Suggested next step: once the Orders API is public, open an issue or PR in relayprotocol/relay-docs by hand. Start with the feature guide and the API reference pages, and use the fastFill SDK action page as the template for the action pages. Don't use /publish-docs-pr, because it would publish a low-confidence draft.

Comment thread packages/sdk/src/actions/orders.ts Outdated
@@ -0,0 +1,185 @@
import type { AxiosRequestConfig } from 'axios'

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we break this file into separate files for each action which is the preexisting pattern here. We can put them into a folder called "orders" to organize them better.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 11da509. Each action now has its own file under packages/sdk/src/actions/orders/: createOrder.ts, getOrders.ts, signOrder.ts, cancelOrder.ts and executeOrder.ts, plus an index.ts that re-exports them. The shared request helper lives in requestOrders.ts and is not exported. The public exports are unchanged, and the tests moved to orders/orders.test.ts.

This branch was successfully deployed

1 active deployment
Preview — 11da509f Deployed Nov 14, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants