fix(predict): refresh balance/allowance before Polymarket order submission (MetaMask#26954)

## **Description**

Polymarket's CLOB infrastructure is intermittently returning 400 errors
with "not enough balance / allowance" when placing orders at high
request rates. As a temporary workaround communicated by the Polymarket
team, we now call `GET /balance-allowance/update` before each order to
refresh the balance/allowance state on their end.

### Changes:
- **`utils.ts`**: Add `refreshBalanceAllowance()` utility that calls the
CLOB balance-allowance/update endpoint with L2 HMAC auth headers
  - BUY orders → `asset_type=COLLATERAL` (USDC)
  - SELL orders → `asset_type=CONDITIONAL` with the order's `token_id`
- **`PolymarketProvider.ts`**: Call `refreshBalanceAllowance()` in
`placeOrder()` right before `submitClobOrder()`, wrapped in try/catch so
failures don't block order submission
- **`utils.test.ts`**: 5 new tests covering BUY/SELL paths, auth
headers, error resilience, and custom signature types
- **`PolymarketProvider.test.ts`**: 4 new integration tests verifying
call ordering, parameter passing for both sides, and graceful
degradation on refresh failure

> **Note**: This is a temporary workaround. TODO comments are in place
for removal once Polymarket resolves the underlying infrastructure
issue.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/PRED-726

## **Manual testing steps**

```gherkin
Feature: Polymarket order placement with balance/allowance refresh

  Scenario: user places a BUY order on a prediction market
    Given the user has USDC deposited in their Polymarket proxy wallet

    When user places a BUY order on any market
    Then the balance/allowance refresh call fires before the order submission
    And the order completes successfully

  Scenario: user places a SELL order on a prediction market
    Given the user holds outcome tokens for a market

    When user places a SELL order
    Then the balance/allowance refresh call fires with the token_id before the order
    And the order completes successfully

  Scenario: balance/allowance refresh endpoint is down
    Given the refresh endpoint returns an error

    When user places any order
    Then the order submission still proceeds normally
```

## **Screenshots/Recordings**

N/A — no UI changes

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds a new preflight network call in the order placement path; while
failures are best-effort and don’t block orders, it changes
timing/behavior in a core trading flow and could affect reliability or
rate limits.
> 
> **Overview**
> Adds a temporary workaround for intermittent Polymarket CLOB `not
enough balance / allowance` errors by introducing
`refreshBalanceAllowance()` (calls `GET /balance-allowance/update` with
L2 HMAC headers) and invoking it in `PolymarketProvider.placeOrder()`
immediately before `submitClobOrder()`.
> 
> The refresh is **best-effort** (wrapped in `try/catch` with logging)
and varies request params by side: **BUY** refreshes
`asset_type=COLLATERAL`, **SELL** refreshes `asset_type=CONDITIONAL`
with `token_id`. Updates unit/integration tests to cover parameter
selection, call ordering, header usage, and non-blocking behavior on
refresh failure.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
8a46817. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: matallui

app/components/UI/Predict/providers/polymarket/PolymarketProvider.test.ts

@@ -69,6 +69,7 @@ import {
   parsePolymarketPositions,
   previewOrder,
   priceValid,
+  refreshBalanceAllowance,
   submitClobOrder,
 } from './utils';
 
@@ -109,6 +110,7 @@ jest.mock('./utils', () => {
     priceValid: jest.fn(),
     createApiKey: jest.fn(),
     submitClobOrder: jest.fn(),
+    refreshBalanceAllowance: jest.fn(),
     getMarketPositions: jest.fn(),
     getBalance: jest.fn(),
     previewOrder: jest.fn(),
@@ -212,6 +214,7 @@ const mockParsePolymarketPositions = parsePolymarketPositions as jest.Mock;
 const mockPriceValid = priceValid as jest.Mock;
 const mockCreateApiKey = createApiKey as jest.Mock;
 const mockSubmitClobOrder = submitClobOrder as jest.Mock;
+const mockRefreshBalanceAllowance = refreshBalanceAllowance as jest.Mock;
 const mockEncodeClaim = encodeClaim as jest.Mock;
 const mockComputeProxyAddress = computeProxyAddress as jest.Mock;
 const mockCreatePermit2FeeAuthorization =
@@ -1603,6 +1606,97 @@ describe('PolymarketProvider', () => {
     });
   });
 
+  describe('placeOrder balance/allowance refresh workaround', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
+      mockRefreshBalanceAllowance.mockResolvedValue(undefined);
+    });
+
+    it('calls refreshBalanceAllowance with COLLATERAL before submitting a BUY order', async () => {
+      // Arrange
+      const { provider, mockSigner } = setupPlaceOrderTest();
+      const preview = createMockOrderPreview({ side: Side.BUY });
+
+      // Act
+      await provider.placeOrder({ signer: mockSigner, preview });
+
+      // Assert
+      expect(mockRefreshBalanceAllowance).toHaveBeenCalledWith({
+        address: mockSigner.address,
+        apiKey: expect.objectContaining({ apiKey: 'test-api-key' }),
+        side: Side.BUY,
+        outcomeTokenId: preview.outcomeTokenId,
+      });
+    });
+
+    it('calls refreshBalanceAllowance with CONDITIONAL before submitting a SELL order', async () => {
+      // Arrange
+      const { provider, mockSigner } = setupPlaceOrderTest();
+      const preview = createMockOrderPreview({ side: Side.SELL });
+
+      // Act
+      await provider.placeOrder({ signer: mockSigner, preview });
+
+      // Assert
+      expect(mockRefreshBalanceAllowance).toHaveBeenCalledWith({
+        address: mockSigner.address,
+        apiKey: expect.objectContaining({ apiKey: 'test-api-key' }),
+        side: Side.SELL,
+        outcomeTokenId: preview.outcomeTokenId,
+      });
+    });
+
+    it('calls refreshBalanceAllowance before submitClobOrder', async () => {
+      // Arrange
+      const { provider, mockSigner } = setupPlaceOrderTest();
+      const callOrder: string[] = [];
+      mockRefreshBalanceAllowance.mockImplementation(async () => {
+        callOrder.push('refresh');
+      });
+      mockSubmitClobOrder.mockImplementation(async () => {
+        callOrder.push('submit');
+        return {
+          success: true,
+          response: {
+            success: true,
+            makingAmount: '1000000',
+            orderID: 'order-123',
+            status: 'success',
+            takingAmount: '0',
+            transactionsHashes: [],
+          },
+          error: undefined,
+        };
+      });
+      const preview = createMockOrderPreview({ side: Side.BUY });
+
+      // Act
+      await provider.placeOrder({ signer: mockSigner, preview });
+
+      // Assert
+      expect(callOrder).toEqual(['refresh', 'submit']);
+    });
+
+    it('proceeds with order submission when refreshBalanceAllowance fails', async () => {
+      // Arrange
+      const { provider, mockSigner } = setupPlaceOrderTest();
+      mockRefreshBalanceAllowance.mockRejectedValue(
+        new Error('Network timeout'),
+      );
+      const preview = createMockOrderPreview({ side: Side.BUY });
+
+      // Act
+      const result = await provider.placeOrder({
+        signer: mockSigner,
+        preview,
+      });
+
+      // Assert - order still submitted despite refresh failure
+      expect(mockSubmitClobOrder).toHaveBeenCalled();
+      expect(result.success).toBe(true);
+    });
+  });
+
   describe('placeOrder with Safe fee authorization', () => {
     it('computes Safe address before creating order', async () => {
       const { provider, mockSigner } = setupPlaceOrderTest();

app/components/UI/Predict/providers/polymarket/PolymarketProvider.ts

@@ -102,6 +102,7 @@ import {
   parsePolymarketEvents,
   parsePolymarketPositions,
   previewOrder,
+  refreshBalanceAllowance,
   roundOrderAmount,
   submitClobOrder,
 } from './utils';
@@ -1306,6 +1307,23 @@ export class PolymarketProvider implements PredictProvider {
         apiKey: signerApiKey,
       });
 
+      // TEMPORARY WORKAROUND: Refresh balance/allowance on Polymarket's CLOB
+      // before submitting the order. See refreshBalanceAllowance docs for details.
+      try {
+        await refreshBalanceAllowance({
+          address: signer.address,
+          apiKey: signerApiKey,
+          side,
+          outcomeTokenId,
+        });
+      } catch (refreshError) {
+        // Best-effort — don't block order submission if the refresh fails
+        DevLogger.log(
+          'PolymarketProvider: Pre-order balance/allowance refresh failed',
+          refreshError,
+        );
+      }
+
       const { success, response, error } = await submitClobOrder({
         headers,
         clobOrder,

app/components/UI/Predict/providers/polymarket/utils.test.ts

@@ -60,6 +60,7 @@ import {
   parsePolymarketPositions,
   parsePolymarketActivity,
   priceValid,
+  refreshBalanceAllowance,
   submitClobOrder,
   decimalPlaces,
   roundNormal,
@@ -701,6 +702,100 @@ describe('polymarket utils', () => {
     });
   });
 
+  describe('refreshBalanceAllowance', () => {
+    beforeEach(() => {
+      mockFetch.mockReset();
+      (global.crypto as any).createHmac.mockReturnValue({
+        update: jest.fn().mockReturnThis(),
+        digest: jest.fn().mockReturnValue('mock-digest-base64'),
+      });
+    });
+
+    it('sends COLLATERAL asset_type for BUY orders', async () => {
+      mockFetch.mockResolvedValue({ ok: true });
+
+      await refreshBalanceAllowance({
+        address: mockAddress,
+        apiKey: mockApiKey,
+        side: Side.BUY,
+        outcomeTokenId: 'token-123',
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('/balance-allowance/update?'),
+        expect.objectContaining({ method: 'GET' }),
+      );
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain('asset_type=COLLATERAL');
+      expect(calledUrl).toContain('signature_type=2');
+      expect(calledUrl).not.toContain('token_id=');
+    });
+
+    it('sends CONDITIONAL asset_type with token_id for SELL orders', async () => {
+      mockFetch.mockResolvedValue({ ok: true });
+
+      await refreshBalanceAllowance({
+        address: mockAddress,
+        apiKey: mockApiKey,
+        side: Side.SELL,
+        outcomeTokenId: 'token-456',
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain('asset_type=CONDITIONAL');
+      expect(calledUrl).toContain('token_id=token-456');
+      expect(calledUrl).toContain('signature_type=2');
+    });
+
+    it('calls CLOB_ENDPOINT with L2 auth headers', async () => {
+      mockFetch.mockResolvedValue({ ok: true });
+
+      await refreshBalanceAllowance({
+        address: mockAddress,
+        apiKey: mockApiKey,
+        side: Side.BUY,
+        outcomeTokenId: 'token-123',
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toMatch(/^https:\/\/clob\.polymarket\.com/);
+      const calledOptions = mockFetch.mock.calls[0][1] as RequestInit;
+      expect(calledOptions.headers).toEqual(
+        expect.objectContaining({
+          POLY_ADDRESS: mockAddress,
+        }),
+      );
+    });
+
+    it('does not throw when response is not ok', async () => {
+      mockFetch.mockResolvedValue({ ok: false, status: 500 });
+
+      await expect(
+        refreshBalanceAllowance({
+          address: mockAddress,
+          apiKey: mockApiKey,
+          side: Side.BUY,
+          outcomeTokenId: 'token-123',
+        }),
+      ).resolves.toBeUndefined();
+    });
+
+    it('uses custom signatureType when provided', async () => {
+      mockFetch.mockResolvedValue({ ok: true });
+
+      await refreshBalanceAllowance({
+        address: mockAddress,
+        apiKey: mockApiKey,
+        side: Side.BUY,
+        outcomeTokenId: 'token-123',
+        signatureType: SignatureType.EOA,
+      });
+
+      const calledUrl = mockFetch.mock.calls[0][0] as string;
+      expect(calledUrl).toContain('signature_type=0');
+    });
+  });
+
   describe('submitClobOrder', () => {
     const mockHeaders: ClobHeaders = {
       POLY_ADDRESS: mockAddress,

app/components/UI/Predict/providers/polymarket/utils.ts

@@ -61,6 +61,7 @@ import {
   PolymarketApiMarket,
   PolymarketApiTeam,
   PolymarketPosition,
+  SignatureType,
   TickSize,
   OrderBook,
 } from './types';
@@ -187,6 +188,76 @@ export const getL2Headers = async ({
   return headers;
 };
 
+/**
+ * TEMPORARY WORKAROUND for Polymarket infrastructure issue.
+ *
+ * Polymarket's CLOB infrastructure intermittently returns 400 errors with
+ * "not enough balance / allowance" when placing orders at high request rates.
+ * Calling this endpoint before each order refreshes the balance/allowance state
+ * on their end and prevents most of these spurious failures.
+ *
+ * For BUY orders: refreshes COLLATERAL (USDC) balance/allowance.
+ * For SELL orders: refreshes CONDITIONAL token balance/allowance.
+ *
+ * TODO: Remove this workaround once Polymarket resolves the underlying
+ * infrastructure issue. Track removal in a follow-up ticket.
+ */
+export const refreshBalanceAllowance = async ({
+  address,
+  apiKey,
+  side,
+  outcomeTokenId,
+  signatureType = SignatureType.POLY_GNOSIS_SAFE,
+}: {
+  address: string;
+  apiKey: ApiKeyCreds;
+  side: Side;
+  outcomeTokenId: string;
+  signatureType?: SignatureType;
+}): Promise<void> => {
+  const { CLOB_ENDPOINT } = getPolymarketEndpoints();
+
+  const queryParams = new URLSearchParams({
+    signature_type: String(signatureType),
+  });
+
+  if (side === Side.BUY) {
+    queryParams.set('asset_type', 'COLLATERAL');
+  } else {
+    queryParams.set('asset_type', 'CONDITIONAL');
+    queryParams.set('token_id', outcomeTokenId);
+  }
+
+  const requestPath = `/balance-allowance/update`;
+
+  const headers = await getL2Headers({
+    l2HeaderArgs: {
+      method: 'GET',
+      requestPath,
+    },
+    address,
+    apiKey,
+  });
+
+  const response = await fetch(
+    `${CLOB_ENDPOINT}${requestPath}?${queryParams.toString()}`,
+    {
+      method: 'GET',
+      headers,
+    },
+  );
+
+  if (!response.ok) {
+    DevLogger.log(
+      'refreshBalanceAllowance: Pre-order balance/allowance refresh failed',
+      {
+        status: response.status,
+        side,
+      },
+    );
+  }
+};
+
 export const deriveApiKey = async ({ address }: { address: string }) => {
   const { CLOB_ENDPOINT } = getPolymarketEndpoints();
   const headers = await getL1Headers({ address });