chore: add signatures endpoint

Author: einaralex

apps/customer/app/test/page.tsx

@@ -33,6 +33,7 @@ import {
   usePlaceOrder,
   useProfile,
   useRequestIban,
+  useSignatures,
   useSubmitProfileDetails,
   useSubscribeOrderNotification,
   useTokens,
@@ -95,6 +96,7 @@ export default function Test() {
   });
 
   const { data: tokens } = useTokens();
+  const { data: signatures } = useSignatures();
 
   /**
    * Monerium mutations
@@ -855,6 +857,13 @@ export default function Test() {
                 <PrettyPrintJson data={tokens} />
               </details>
             </div>
+            <div>
+              <h2>Signatures</h2>
+              <details>
+                <summary>Click to Expand, total: {signatures?.total}</summary>
+                <PrettyPrintJson data={signatures} />
+              </details>
+            </div>
           </div>
           <br />
 

packages/sdk-react-provider/src/lib/hooks.tsx

@@ -24,6 +24,8 @@ import MoneriumClient, {
   ProfilesResponse,
   RequestIbanPayload,
   ResponseStatus,
+  SignaturesQueryParams,
+  SignaturesResponse,
   SubmitProfileDetailsPayload,
   Token,
 } from '@monerium/sdk';
@@ -86,6 +88,11 @@ export const keys = {
   requestIban: ['monerium', 'request-iban'],
   placeOrder: ['monerium', 'place-order'],
   linkAddress: ['monerium', 'link-address'],
+  getSignatures: (filter?: unknown) => [
+    'monerium',
+    'signatures',
+    ...(filter ? [filter] : []),
+  ],
 };
 
 /** Internal hook to use SDK */
@@ -998,6 +1005,72 @@ export function usePlaceOrder({
     ...rest,
   };
 }
+/**
+ * Get pending signatures for the authenticated user.
+ *
+ * Returns pending signatures that require user action, such as order signatures
+ * or link address signatures. Accepts filtering by address, chain, kind, and profile.
+ *
+ * @group Hooks
+ * @category Signatures
+ * @param {Object} params
+ * @param {SignaturesQueryParams} params.query - Optional query parameters to filter signatures
+ *
+ * @example
+ * ```ts
+ * // Get all pending signatures
+ * const {
+ *    data: signatures,
+ *    isLoading,
+ *    isError,
+ *    error,
+ *    refetch,
+ *    ...moreUseQueryResults
+ * } = useSignatures();
+ *
+ * // Get pending order signatures for a specific address
+ * const { data: orderSignatures } = useSignatures({
+ *   query: {
+ *     address: '0x1234...',
+ *     kind: 'order'
+ *   }
+ * });
+ *
+ * // Check the kind of signature
+ * signatures?.pending.forEach(sig => {
+ *   if (sig.kind === 'order') {
+ *     console.log('Order signature:', sig.id, sig.amount);
+ *   } else {
+ *     console.log('Link address signature');
+ *   }
+ * });
+ * ```
+ * @see {@link https://monerium.dev/api-docs-v2#tag/signatures/operation/get-signatures | API Documentation}
+ */
+export function useSignatures({
+  query,
+  options,
+}: {
+  query?: SignaturesQueryParams;
+  /** {@inheritDoc QueryOptions} */
+  options?: QueryOptions<SignaturesResponse>;
+} = {}) {
+  const sdk = useSdk();
+  const { isAuthorized } = useAuth();
+
+  return useQuery<SignaturesResponse>({
+    ...options,
+    queryKey: keys.getSignatures(query),
+    queryFn: () => {
+      if (!sdk) {
+        throw new Error('No SDK instance available');
+      }
+      return sdk.getSignatures(query);
+    },
+    enabled: Boolean(sdk && isAuthorized && (options?.enabled ?? true)),
+  });
+}
+
 /**
  * # Add address to profile.
  *

packages/sdk/src/client.ts

@@ -51,6 +51,8 @@ import type {
   RefreshTokenPayload,
   RequestIbanPayload,
   ResponseStatus,
+  SignaturesQueryParams,
+  SignaturesResponse,
   SubmitProfileDetailsPayload,
   SupportingDoc,
   Token,
@@ -555,6 +557,43 @@ export class MoneriumClient {
     return this.#api<Token[]>('get', 'tokens');
   }
 
+  /**
+   * Get pending signatures for the authenticated user.
+   *
+   * Returns pending signatures that require user action, such as order signatures
+   * or link address signatures. Accepts filtering by address, chain, kind, and profile.
+   *
+   * @group Signatures
+   * @param {SignaturesQueryParams} [params] - Optional query parameters to filter signatures
+   * @see {@link https://monerium.dev/api-docs-v2#tag/signatures/operation/get-signatures | API Documentation}
+   *
+   * @example
+   * ```ts
+   * // Get all pending signatures
+   * const signatures = await monerium.getSignatures();
+   *
+   * // Get pending order signatures for a specific address
+   * const orderSignatures = await monerium.getSignatures({
+   *   address: '0x1234...',
+   *   kind: 'order'
+   * });
+   *
+   * // Get pending signatures on a specific chain
+   * const polygonSignatures = await monerium.getSignatures({
+   *   chain: 'polygon'
+   * });
+   * ```
+   */
+  getSignatures(params?: SignaturesQueryParams): Promise<SignaturesResponse> {
+    const queryParameters = params
+      ? mapChainIdToChain(this.#env.name, params)
+      : undefined;
+    return this.#api<SignaturesResponse>(
+      'get',
+      `signatures${queryParams(queryParameters)}`
+    );
+  }
+
   /**
    * Add a new address to the profile
    * @group Addresses
@@ -574,25 +613,11 @@ export class MoneriumClient {
    *
    * **Note:** For multi-signature orders, the API returns a 202 Accepted response
    * with `{status: 202, statusText: "Accepted"}` instead of the full Order object.
-   * Check if the response has an `id` property to determine if it's a full Order.
    *
    * @returns Promise that resolves to either:
    * - `Order` - Full order object for regular orders
    * - `ResponseStatus` - Status object with `{status: 202, statusText: "Accepted"}` for multi-sig orders
    *
-   * @example
-   * ```ts
-   * const result = await monerium.placeOrder(orderData);
-   *
-   * if ('id' in result) {
-   *   // Regular order - full Order object
-   *   console.log('Order placed:', result.id);
-   * } else {
-   *   // Multi-sig order - 202 Accepted
-   *   console.log('Multi-sig order accepted:', result.status);
-   * }
-   * ```
-   *
    * @see {@link https://monerium.dev/api-docs-v2#tag/orders/operation/post-orders | API Documentation}
    *
    * @group Orders

packages/sdk/src/types.ts

@@ -684,3 +684,69 @@ export type ResponseStatus = {
   status: number;
   statusText: string;
 };
+
+// -- Signatures
+
+/**
+ * Type of pending signature
+ */
+export type PendingSignatureKind = 'linkAddress' | 'order';
+
+/**
+ * Base interface for pending signatures
+ */
+interface PendingSignatureBase {
+  kind: PendingSignatureKind;
+  chain: Chain;
+  address: string;
+  createdAt: string;
+}
+
+/**
+ * Pending signature for an order
+ */
+export interface PendingOrderSignature extends PendingSignatureBase {
+  id: string;
+  kind: 'order';
+  amount: string;
+  counterpart: Counterpart;
+  currency: Currency;
+}
+
+/**
+ * Pending signature for linking an address
+ */
+export interface PendingLinkAddressSignature extends PendingSignatureBase {
+  kind: 'linkAddress';
+}
+
+/**
+ * Union type for all pending signature types
+ */
+export type PendingSignature =
+  | PendingOrderSignature
+  | PendingLinkAddressSignature;
+
+/**
+ * Query parameters for fetching pending signatures
+ */
+export interface SignaturesQueryParams {
+  /** Filter by blockchain address */
+  address?: string;
+  /** Filter by blockchain network */
+  chain?: Chain | ChainId;
+  /** Filter by signature request kind */
+  kind?: PendingSignatureKind;
+  /** UUID of the profile (defaults to authenticated user's default profile) */
+  profile?: string;
+}
+
+/**
+ * Response from the signatures endpoint
+ */
+export interface SignaturesResponse {
+  /** Array of pending signatures */
+  pending: PendingSignature[];
+  /** Total number of pending signatures */
+  total: number;
+}