Phantom Connect SDK

The SDK can automatically reconnect to existing sessions to provide a seamless experience. This is controlled by the autoConnect option.

• autoConnect: true (Default for embedded): The SDK checks for a valid session immediately upon instantiation. If a session exists, it connects in the background.
• autoConnect: false: You must manually call sdk.connect() every time the user needs to authenticate.

Pattern for checking connection: Always check sdk.isConnected() (or sdk.solana.isConnected / sdk.ethereum.isConnected()) before attempting to use the SDK to determine if a manual connect() call is required.

const sdk = new BrowserSDK({
  providers: ["google", "apple"],
  appId: "your-app-id",
  addressTypes: [AddressType.solana],
  autoConnect: true,
});

if (sdk.isConnected()) {
  // Use existing session
  const addresses = await sdk.getAddresses();
} else {
  // Trigger manual connection
  await sdk.connect({ provider: "google" });
}

For use cases requiring a second signer (e.g., your backend acting as a fee payer), use the presignTransaction option within signAndSendTransaction.

Important Constraints:

• Phantom embedded wallets do not accept pre-signed transactions. You must use this option to allow Phantom to construct/validate the transaction before your backend co-signs it.
• This restriction does not apply to injected providers (like the Phantom browser extension).
• presignTransaction only applies to Solana transactions via the embedded provider. EVM and injected providers are unaffected.
• Security: Never hold a fee payer keypair in frontend code. The callback should call your backend to perform the partial signing.

import { useSolana, base64urlDecode, base64urlEncode } from "@phantom/react-sdk";
import { VersionedTransaction } from "@solana/web3.js";

function SendWithFeeSponsor() {
  const { solana } = useSolana();

  const sendSponsored = async () => {
    const result = await solana.signAndSendTransaction(transaction, {
      presignTransaction: async (tx, context) => {
        // Send the transaction to your backend for fee payer signing.
        const response = await fetch("/api/presign", {
          method: "POST",
          body: JSON.stringify({ transaction: tx, networkId: context.networkId }),
          headers: { "Content-Type": "application/json" },
        });
        const { transaction: signedTx } = await response.json();
        return signedTx; // base64url-encoded, partially signed by the fee payer
      },
    });
  };
}

The Connect SDK signing APIs automatically bind every EVM transaction to its selected network before the transaction is sent to the signing service.

To ensure security and prevent replay attacks, the SDK follows these rules:

1. Chain ID Derivation: The SDK derives the expected chainId from a supported eip155 networkId.
2. Automatic Filling: For structured legacy and typed transactions, if the chainId is omitted or set to zero, the SDK replaces it with the expected value derived from the selected network.
3. Validation: If you provide a non-zero chainId, it must be valid, supported, and exactly match the selected network.
4. Raw Transactions: Raw hex and byte inputs are decoded as unsigned EVM transactions and subjected to the same validation rules.

Rejection Criteria: Transactions will be rejected before signing if they contain:

• Malformed encodings
• Already-signed transactions
• Unsupported chain IDs
• Network mismatches

Chain ID Formats: Chain IDs must be provided as either a decimal string (e.g., "137") or a hexadecimal string (e.g., "0x89"). Other string formats are considered invalid.

When the API returns a 402 status, the client throws a PaymentRequiredError. You have two ways to handle this:

Option A: Manual Handling

Catch the error and inspect the payment object to get details like network, token, amount, preparedTx, and description.

Option B: Automatic Payment Handling

Provide a handler via setPaymentHandler(). When a 402 occurs, the client will execute this handler, and if it returns a signature, the client will automatically retry the original request. The signature is stored via setPaymentSignature() and sent as the X-Payment header on all subsequent requests.

import { PaymentRequiredError } from "@phantom/phantom-api-client";

// Option A — manual catch
try {
  const data = await client.get("/swap/v2/quotes");
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    console.log(err.payment); // { network, token, amount, preparedTx, description }
  }
}

// Option B — automatic handler
client.setPaymentHandler(async payment => {
  // Sign and broadcast the prepared transaction, return the signature
  const signature = await wallet.signAndSend(payment.preparedTx);
  return signature;
});

// Requests now auto-pay on 402 and retry transparently
const data = await client.get("/swap/v2/quotes");

If your application needs to act as a fee payer (co-signing), use the presignTransaction option within signAndSendTransaction.

Important Constraints:

• This feature is only available for Solana transactions via the embedded provider.
• EVM transactions are unaffected.
• Phantom embedded wallets do not accept pre-signed transactions. The presignTransaction callback must be used so that Phantom can construct and validate the transaction before your app applies the second signature.

Workflow:

1. Phantom constructs/validates the transaction.
2. The presignTransaction callback is triggered.
3. Your app deserializes the transaction, adds its signature, and returns the serialized bytes.

import { useSolana, base64urlDecode, base64urlEncode } from "@phantom/react-native-sdk";
import { Keypair, VersionedTransaction } from "@solana/web3.js";

const feePayerKeypair = Keypair.fromSecretKey(new Uint8Array([...]));

function SendWithFeeSponsor() {
  const { solana } = useSolana();

  const sendSponsored = async () => {
    const result = await solana.signAndSendTransaction(transaction, {
      presignTransaction: async (tx, context) => {
        // 1. Decode the transaction bytes
        const txBytes = base64urlDecode(tx);
        const versionedTx = VersionedTransaction.deserialize(txBytes);
        
        // 2. Add the fee payer signature
        versionedTx.sign([feePayerKeypair]);
        
        // 3. Return the re-serialized transaction
        return base64urlEncode(versionedTx.serialize());
      },
    });
  };
}