Internal Accounts

Export internal account wallet credentials

Changed on

Export the wallet credentials of an Embedded Wallet internal account. The returned wallet credentials are HPKE-encrypted to the clientPublicKey supplied in the request body.

Export is a two-step signed-retry flow (same pattern as add-additional credential, revoke credential, and revoke session):

  1. Call POST /internal-accounts/{id}/export with the request body { "clientPublicKey": "..." } and no signature headers. Grid binds the clientPublicKey into the payloadToSign it returns, so the subsequent stamp in Grid-Wallet-Signature commits to the target encryption key. The response is 202 with payloadToSign, requestId, and expiresAt.

  2. Use the session API keypair of a verified authentication credential on the same internal account to build an API-key stamp over payloadToSign, then retry with that full stamp as the Grid-Wallet-Signature header and the requestId echoed back as the Request-Id header. The retry body must carry the same clientPublicKey submitted in step 1 — Grid rejects the retry with 401 if it disagrees with what was bound into payloadToSign. The signed retry returns 200 with encryptedWalletCredentials, which the client decrypts with the matching private key.

The export may not settle within that request: an approval- or consensus-gated wallet-provider activity answers 200 with status: "PROCESSING" instead. The credentials are never stored server-side, so collecting them is the client's job — re-send the byte-identical signed retry (same headers, same body) until it returns encryptedWalletCredentials. The Request-Id challenge stays usable until an attempt actually delivers them, so a PROCESSING response never burns it; a delivered export does, and a later re-send is then rejected with 401. Subscribe to wallet_operation.completed to learn when re-sending will succeed rather than polling blind.

The clientPublicKey is ephemeral: generate a fresh P-256 keypair for this export and discard the private key after decrypting. Send it as an uncompressed key in lowercase hex (130 characters, 04 prefix). Do not reuse the keypair from a verify or refresh call. That private key is the session signing key.

post/internal-accounts/{id}/export

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/export
  • Auth
    HTTP basic

Path parameters

idstring required

The id of the internal account to export.

Headers

Grid-Wallet-Signaturestring

Full API-key stamp built over the prior payloadToSign with the session API keypair of a verified authentication credential on the target internal account. Required on the signed retry; ignored on the initial call.

Request-Idstring

The requestId returned in a prior 202 response, echoed back exactly on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry; must be paired with Grid-Wallet-Signature.

Request body

clientPublicKeystring required

Fresh P-256 public key as an uncompressed SEC1 point in lowercase hex: 130 characters, a 04 prefix followed by the 32-byte X and 32-byte Y coordinates. Generate a new key pair for each export and discard the private key after decrypting the response.

Example request

{
  "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
}

Response

Signed retry accepted. Returns the encrypted wallet credentials (InternalAccountExportResponse); or, when the underlying wallet-provider activity is still in flight, a WalletOperationProcessing body with status: "PROCESSING" — the credentials are never stored server-side, so the client re-sends the byte-identical signed retry to collect them once the activity settles. The challenge stays usable until an attempt actually returns credentials.

OR

Example response

{
  "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "encryptedWalletCredentials": "{\"version\":\"v1.0.0\",\"data\":\"7b22656e6361707065645075626c6963223a22303433...\",\"dataSignature\":\"3045022100c9...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"
}

Changes

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • warning

      added the new EXACT_AMOUNT_UNAVAILABLE enum value to the response property for the response status