Request tracing

Starting in 7.3.0, the iOS SDK attaches an X-Portal-Trace-Id header to every HTTP request it makes. Portal’s logs are indexed by that value, so a single trace ID lets you — and Portal support — follow one user-facing action across every request it produced.

Overview

A trace ID is a lowercased UUID v4 sent as the X-Portal-Trace-Id request header. You do not have to do anything to get one: the SDK generates a trace ID for every request. What you gain by supplying your own is correlation — the same value appears in your logs and in Portal’s, so a support ticket goes from “a signing request failed sometime Tuesday” to an exact record.

Automatic tracing

The header is added in three places inside the SDK, so every request path is covered:

Request path	Where the header is set
`PortalAPIRequest`	`init(url:method:payload:bearerToken:traceId:)` seeds the header from `traceId`, or generates one.
`PortalRequests`	`createBaseRequest` adds the header, and backfills it if a custom request omitted it.
Legacy `HttpRequest`	Backfills the header when it is not already present.

iOS attaches the header unconditionally — there is no host allowlist. Requests to custom RPC endpoints you configure with withRpcConfig carry it too, because they are built with the same PortalAPIRequest type. The value is an opaque UUID and contains no client, wallet, or key data, but be aware that a third-party or self-hosted RPC provider will see it. This differs from the Android SDK, which filters the header to Portal-owned hosts.

Supplying your own trace ID

Three public entry points accept a trace ID. Wherever you leave it nil, the SDK generates one for you.

Provider requests

RequestOptions carries the trace ID for portal.request(...) and everything built on top of it:

public struct RequestOptions: Codable {
  public var signatureApprovalMemo: String? = nil
  public var sponsorGas: Bool? = nil
  public var traceId: String? = nil

  public init(
    signatureApprovalMemo: String? = nil,
    sponsorGas: Bool? = nil,
    traceId: String? = nil
  )
}

For requests that need a signature, RequestOptions.traceId is also forwarded into MPC signing metadata as reqId. That means the same value tags both the HTTP request and the MPC operation it triggers — one lookup covers the API call and the signing work behind it. That is the payoff, and it is not something you can reconstruct after the fact.

Sending assets

SendAssetParams gained a traceId:

public struct SendAssetParams: Codable {
  public let to: String
  public let amount: String
  public let token: String
  public let signatureApprovalMemo: String?
  public var sponsorGas: Bool?
  public var traceId: String?

  public init(
    to: String,
    amount: String,
    token: String,
    signatureApprovalMemo: String? = nil,
    sponsorGas: Bool? = nil,
    traceId: String? = nil
  )
}

Raw signing

rawSign takes the trace ID as an argument. Unlike the other two, it is not defaulted — on this overload you must pass a value, even if that value is nil:

public func rawSign(
  message: String,
  chainId: String,
  signatureApprovalMemo: String? = nil,
  traceId: String?
) async throws -> PortalProviderResult

import PortalSwift

let traceId = generateTraceId()

do {
  let response = try await portal.rawSign(
    message: "74657374", // Must be in hex format — "test" is "74657374" in hex.
    chainId: "eip155:11155111",
    signatureApprovalMemo: "Sign login challenge",
    traceId: traceId
  )

  if let signature = response.result as? String {
    print("✅ Signed with trace ID \(traceId): \(signature)")
  }
} catch {
  print("❌ Signing failed with trace ID \(traceId): \(error)")
}

Existing calls keep compiling. PortalProtocol ships back-compatible extensions for rawSign(message:chainId:) and rawSign(message:chainId:signatureApprovalMemo:), both of which pass traceId: nil.

When an SDK operation makes several requests, all of them carry the same trace ID. This is what makes tracing worth using — you get one handle for the whole flow instead of one per request.

Operation	Trace ID source
`sendAsset` — build, sign, broadcast	`SendAssetParams.traceId`, or generated
`portal.evmAccountType.upgradeTo7702` — status, build authorization list, raw sign, build transaction	Always generated internally
MPC generate, backup, recover, eject	Always generated internally

MPC and EIP-7702 operations do not accept a trace ID. They generate one per operation and share it across their sub-requests, but you cannot supply your own. If you need to correlate an MPC flow with your own logs, see Reading the ID back.

Generate one trace ID per user-facing action — “send USDC”, “sign in” — not per request. A trace ID that maps one-to-one onto HTTP requests tells you nothing you did not already know.

Reading the id back

PortalMpcBackupResponse gained a traceId property. It is the only place the SDK hands a generated trace ID back to you:

public struct PortalMpcBackupResponse {
  public let cipherText: String
  public let shareIds: [String]
  public let traceId: String

  public init(cipherText: String, shareIds: [String], traceId: String)
}

That type is returned by PortalMpcProtocol.backup(_:usingProgressCallback:). Note that portal.backupWallet(_:usingProgressCallback:) returns a (cipherText:storageCallback:) tuple and does not surface the trace ID — so if you go through Portal rather than PortalMpc directly, the backup trace ID is not available to you.

No other response type exposes a trace ID. For every flow other than PortalMpc.backup, the way to know the trace ID is to supply it yourself.

Helpers

Two symbols are public:

/// The trace ID header used by connect-api (client + custodian APIs).
public let PORTAL_TRACE_ID_HEADER = "X-Portal-Trace-Id"

/// Generates a UUID v4 trace ID for request correlation.
public func generateTraceId() -> String

Use generateTraceId() rather than rolling your own. It is the same generator the SDK uses internally, and it produces the lowercase UUID v4 format that Portal’s logs expect. Generate the ID once, log it, then thread it through the whole action:

import PortalSwift

let traceId = generateTraceId()
print("Starting transfer — portalTraceId: \(traceId)")

do {
  let response = try await portal.sendAsset(
    chainId: "eip155:11155111",
    params: SendAssetParams(
      to: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      amount: "0.01",
      token: "NATIVE",
      traceId: traceId
    )
  )

  print("Transfer submitted — portalTraceId: \(traceId), txHash: \(response.txHash)")
} catch {
  print("Transfer failed — portalTraceId: \(traceId), error: \(error)")
}

The same ID reaches buildEip155Transaction, the eth_sendTransaction provider request, and the MPC signing operation behind it. For a provider request, pass it through RequestOptions:

import PortalSwift

let chainId = "eip155:11155111"
let traceId = generateTraceId()

do {
  let transactionParam = BuildTransactionParam(
    to: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    token: "USDC",
    amount: "1"
  )

  let txDetails = try await portal.buildEip155Transaction(
    chainId: chainId,
    params: transactionParam
  )

  let response = try await portal.request(
    chainId: chainId,
    method: .eth_sendTransaction,
    params: [txDetails.transaction],
    options: RequestOptions(signatureApprovalMemo: "Send USDC", traceId: traceId)
  )

  guard let txHash = response.result as? String else {
    print("Unexpected response — portalTraceId: \(traceId)")
    return
  }

  print("✅ Transaction hash: \(txHash) — portalTraceId: \(traceId)")
} catch {
  print("❌ Request failed — portalTraceId: \(traceId), error: \(error)")
}

portal.buildEip155Transaction(chainId:params:) does not accept a trace ID, so in the example above the build request carries a generated one and only the eth_sendTransaction leg carries yours. If you want a single trace ID across build, sign, and broadcast, use sendAsset with SendAssetParams(traceId:) instead of building and requesting separately.

See Configure log level if you also want the SDK’s own output alongside your trace IDs. Log the trace ID next to your own request identifier, so you can look up either from the other. When something fails, include the trace ID in your support ticket or bug report — it is the fastest path from a user complaint to the exact requests Portal handled.

A trace ID is not a secret, but it is a correlation handle. Do not log it in a system that stores user PII under a different retention policy than your Portal logs — that turns a debugging aid into a way to join two datasets you meant to keep separate.

Signature changes in 7.3.0

Threading traceId through the SDK changed several protocol requirements.

If you call Portal’s APIs, 7.3.0 requires no changes — every new parameter is either defaulted or paired with a back-compatible extension. If you implement any Portal protocol — most commonly a hand-rolled test mock — several gained new requirements.

Protocol	Change
`PortalProtocol`	`rawSign(message:chainId:signatureApprovalMemo:traceId:)` — `traceId` is not defaulted on the requirement. Also gained `var ramps: Ramps { get }`, for on/off-ramp support.
`PortalApiProtocol`	`traceId:` added to `eject`, `getClient`, `getClientCipherText`, `prepareEject`, `refreshClient`, `updateShareStatus`, `storeClientCipherText`, `getWalletCapabilities`, `buildEip155Transaction`, `buildSolanaTransaction`, `buildBitcoinP2wpkhTransaction`, and `broadcastBitcoinP2wpkhTransaction` — each with a back-compatible extension. Also gained `var noah: PortalNoahApiProtocol { get }` for Noah, and `generatePreGeneratedShares(metadataStr:traceId:)`, used by the pre-generated wallet feature flag.
`PortalEvmAccountTypeApiProtocol`	`traceId:` added to `getStatus`, `buildAuthorizationList`, and `buildAuthorizationTransaction`, each with a back-compatible extension. See Upgrading to EIP-7702.
`EvmAccountTypePortalDependency`	`rawSign(...)` gained `traceId: String?`.
`PortalSignerProtocol`	`sign(...)` gained `reqId: String?`.

Two call-site changes are genuinely breaking: PortalApi.init gained a parameter. enclaveMPCHost was inserted as the third parameter, before provider:. It is defaulted, so labelled calls are unaffected — but if you construct PortalApi directly and pass arguments positionally, check your call site.

// 7.2.x
let api = PortalApi(
  apiKey: "YOUR_CLIENT_API_KEY",
  apiHost: "api.portalhq.io",
  provider: provider
)

// 7.3.0
let api = PortalApi(
  apiKey: "YOUR_CLIENT_API_KEY",
  apiHost: "api.portalhq.io",
  enclaveMPCHost: "mpc-client.portalhq.io",
  provider: provider
)

PortalMpcBackupResponse gained a memberwise init. init(cipherText:shareIds:traceId:) replaces the two-argument form. Test fixtures that build this type need the extra argument:

// 7.2.x
let response = PortalMpcBackupResponse(
  cipherText: "cipher-text",
  shareIds: ["share-id"]
)

// 7.3.0
let response = PortalMpcBackupResponse(
  cipherText: "cipher-text",
  shareIds: ["share-id"],
  traceId: generateTraceId()
)

Next Steps

Review the generateTraceId reference
Learn about signing transactions
Read Send tokens for the full sendAsset flow
Turn on SDK logging with Configure log level
Check Troubleshooting tips before filing a ticket

Getting Started

SDKs

APIs

Integrations

Resources

Request tracing

Overview

Automatic tracing

Supplying your own trace ID

Provider requests

Sending assets

Raw signing

Reading the id back

Helpers

Signature changes in 7.3.0

Next Steps

​Overview

​Automatic tracing

​Supplying your own trace ID

​Provider requests

​Sending assets

​Raw signing

​Multi-step flows share one ID

​Reading the id back

​Helpers

​Sharing a trace id with Portal support

​Signature changes in 7.3.0

​Next Steps

Overview

Automatic tracing

Supplying your own trace ID

Provider requests

Sending assets

Raw signing

Multi-step flows share one ID

Reading the id back

Helpers

Sharing a trace id with Portal support

Signature changes in 7.3.0

Next Steps