Partner Actions

Partner Actions are the preferred backend-to-backend integration surface for selected partners. They wrap the lower-level quote/build endpoints with:

API-key authentication
Idempotency-Key protection
persisted action IDs
ordered wallet steps
automatic HyperEVM HYPE gas top-up before signature steps when needed
transaction hash submission
polling status
signed webhook notifications

Partner API keys are server-side secrets. Do not ship them in a public web app or mobile bundle.

Create a client

import { createShlpApiClient } from "@arc/shlp-sdk/api";

const shlp = createShlpApiClient({
  baseUrl: "https://portal.signalite.ai",
  partnerApiKey: process.env.SIGNALITE_PARTNER_API_KEY,
});

Create a deposit action

Create a Signalite deposit action only after the wallet already has HyperEVM USDC. For cross-chain funding, Arc/partner code should first use Relay or its own funding rail to move USDC from the selected source network into the user’s EVM wallet on HyperEVM, then create the Partner Action for the actual received HyperEVM USDC amount.

import { parseUsdc } from "@arc/shlp-sdk";

const action = await shlp.createPartnerDepositAction({
  idempotencyKey: `user:${userId}:deposit:${clientRequestId}`,
  amount: parseUsdc("1"),
  account: userAddress,
  receiver: userAddress,
  slippageBps: 50,
});

Use the typed helpers first: createPartnerDepositAction, createPartnerRedeemInstantAction, createPartnerRedeemAsyncAction, createPartnerClaimAction, createPartnerCancelAction, and createPartnerFulfillAction. The generic createPartnerAction remains an escape hatch, but typed helpers avoid malformed body payloads. The response contains steps. Send them in order through the user’s wallet:

for (const step of action.steps) {
  if (!step.tx) continue;

  const hash = await wallet.sendTransaction(step.tx);
  await waitForReceipt(hash);

  if (step.refreshQuoteAfterConfirm) {
    // Approval changed allowance. Create a fresh action/quote before sending
    // the vault deposit transaction.
  }
}

Signalite checks the action wallet’s HYPE balance while creating the Partner Action. If the wallet needs gas and the top-up service is enabled, Signalite sends a small HYPE drip before returning requires_signature steps. If gas sponsorship is disabled or unfunded, action creation fails closed instead of handing the partner wallet steps that cannot execute.

Cross-chain funding rule

Signalite does not bridge source-chain USDC inside Partner Actions. The Partner Action wallet steps are only for HyperEVM chain 999. Use config to discover supported funding sources:

const config = await shlp.getConfig();
const funding = config.deposit.funding;

Arc integration rule:

Quote/execute funding from the selected source network to HyperEVM USDC.
Wait for the user’s HyperEVM USDC balance to reflect the actual received amount.
Create the Signalite deposit Partner Action.
Execute ordered Signalite steps.
Submit only the final Signalite V2 pipe transaction hash.

Do not submit approval hashes, Relay/funding hashes, source-chain hashes, or wrong-chain hashes to POST /api/v1/partner/actions/{id}/submit.

Cross-chain withdrawal receive rule

Partners can request the user’s desired USDC receive chain by passing receiveChainId on withdrawal Partner Actions:

const action = await shlp.createPartnerRedeemAsyncAction({
  idempotencyKey: `user:${userId}:withdraw:${clientRequestId}`,
  shares: sharesRaw,
  account: userAddress,
  slippageBps: 50,
  receiveChainId: 8453, // final receive chain: Base USDC
});

receiveChainId is optional and defaults to 999 for HyperEVM. Valid values come from GET /api/v1/config at withdraw.supportedDestinations. For non-HyperEVM destinations, the Partner Action metadata includes metadata.withdrawal.postSettlementBridge.required=true, but the Relay deposit address is only available when that specific action can route assets now:

redeem_instant: postSettlementBridge.mode="deposit-address" and postSettlementBridge.relay.depositAddress is present.
claim_redeem: postSettlementBridge.mode="deposit-address" and postSettlementBridge.relay.depositAddress is present.
redeem_async: postSettlementBridge.mode="post-claim-quote" and postSettlementBridge.relay=null. This is expected. Persist the selected receiveChainId and pass it again when creating the later claim action.

The wallet step is always a HyperEVM Signalite transaction. For instant redeem or claim to a non-HyperEVM chain, its receiver is the Relay deposit address. For queued redeem, there is no Relay receiver yet because the final fulfilled USDC amount is only known at claim time. The user does not sign a separate USDC approval or Relay bridge deposit after the Signalite withdrawal. For queued withdrawals, persist the selected receiveChainId with the pending redeem in partner state and pass the same value again when creating the later claim action:

await shlp.createPartnerClaimAction({
  idempotencyKey: `user:${userId}:claim:${redeemId}`,
  id: redeemId,
  account: userAddress,
  receiver: userAddress,
  receiveChainId: 8453,
});

Do not submit Relay bridge hashes to Signalite. submitPartnerAction accepts only the final successful HyperEVM Signalite V2 pipe transaction hash. Track the Relay destination delivery with relay.requestId or relay.statusUrl only when the action metadata contains postSettlementBridge.mode="deposit-address". Queued withdraw fulfillment is FIFO. A later smaller withdrawal must remain pending behind an earlier larger request until the keeper can fulfill the earlier request or the earlier user cancels.

Submit the transaction hash

After the wallet sends the primary transaction:

const submitted = await shlp.submitPartnerAction({
  id: action.id,
  txHash,
});

If submitted.status === "indexed", the receipt has already been decoded into canonical Signalite activity/redeem state. The app can show the action as confirmed immediately and refresh position/activity in the background; it does not need to wait for the cron indexer. If submitted.indexingPending === true, the HyperEVM receipt is valid but Signalite has not decoded the action event yet. Keep polling:

const current = await shlp.getPartnerAction(action.id);

Supported action kinds

Action	Endpoint
`deposit`	`POST /api/v1/partner/actions/deposit`
`redeem_instant`	`POST /api/v1/partner/actions/redeem-instant`
`redeem_async`	`POST /api/v1/partner/actions/redeem-async`
`claim_redeem`	`POST /api/v1/partner/actions/claim`
`cancel_redeem`	`POST /api/v1/partner/actions/cancel`
`fulfill_redeem`	`POST /api/v1/partner/actions/fulfill`

Idempotency

Every create request must include a stable Idempotency-Key. Reusing the same key for the same action returns the original action. Reusing it for a different action returns IDEMPOTENCY_CONFLICT. Good key examples:

user_123:deposit:client_request_456
wallet_0xabc:claim:redeem_7

Raw HTTP

POST /api/v1/partner/actions/deposit
Authorization: Bearer <partner_api_key>
Idempotency-Key: user_123:deposit:client_request_456
Content-Type: application/json

{
  "amountRaw": "1000000",
  "account": "0x...",
  "receiver": "0x...",
  "slippageBps": 50
}

Readiness rule

Partner Actions do not bypass product readiness. Still gate UI with /api/v1/health, and treat quote/action business errors as product states, not generic crashes.

Start

Build flows

SDK

Operations

Create a client

Create a deposit action

Cross-chain funding rule

Cross-chain withdrawal receive rule

Submit the transaction hash

Supported action kinds

Idempotency

Raw HTTP

Readiness rule

​Create a client

​Create a deposit action

​Cross-chain funding rule

​Cross-chain withdrawal receive rule

​Submit the transaction hash

​Supported action kinds

​Idempotency

​Raw HTTP

​Readiness rule

Create a client

Create a deposit action

Cross-chain funding rule

Cross-chain withdrawal receive rule

Submit the transaction hash

Supported action kinds

Idempotency

Raw HTTP

Readiness rule