Transaction API

The Transaction API prepares Solana transactions for Swig wallet creation, transfers, swaps, x402 payments, and custom instruction sets. It does not replace required application signatures. Responses include explicit signature requests for embedded secp256r1 and secp256k1 authorization; native Ed25519 signers are represented in the serialized Solana transaction instead.

Supported preparation routes

Method	Route
`POST`	`/transaction/prepare/batch`
`POST`	`/transaction/wallet/create`
`POST`	`/transaction/wallet/rent-claimer/set`
`POST`	`/transaction/wallet/participant-set/create`
`POST`	`/transaction/wallet/role/add`
`POST`	`/transaction/wallet/participant-set/compile`
`POST`	`/transaction/transfer/sol`
`POST`	`/transaction/transfer/spl-token`
`POST`	`/transaction/swap/jupiter`
`POST`	`/transaction/prepare/custom`
`POST`	`/transaction/payment/x402/prepare`

Preparation requests are not retried automatically. A replay can duplicate work, so decide per call whether repeating is correct. The general add-role route attaches a supported authority and one or more typed actions to an existing Swig. The ParticipantSet routes create one threshold set, attach it through that general route, and compile detached member approvals into a simulated transaction. See Add Roles for the general role flow and requester constraints, or Participant Sets for the complete threshold lifecycle, member challenge rules, and current operation support.

Auth

Use an API key:

Authorization: Bearer sk_your_api_key

Common request fields

Field	Type	Description
`network`	enum	`NETWORK_DEVNET` or `NETWORK_MAINNET`
`feePayer`	string	Fee payer public key used in the prepared Solana transaction
`swigAddress`	string	Swig config address for existing-wallet operations
`requesterAuthority`	object	Wallet authority requesting the operation

The x402 preparation route takes its fee payer from the selected offer’s extra.feePayer in paymentRequired.accepts. This route has no top-level feePayer request field.

Prepared transaction response

Most endpoints return a prepared transaction or a response containing prepared transactions.

Field	Type	Description
`transaction`	base64 string	Serialized unsigned or partially signed Solana transaction
`transactionEncoding`	enum	Currently `TRANSACTION_ENCODING_BASE64`
`wallet`	object	`swigConfigAddress` and `walletAddress` when known
`expiresAt`	timestamp	Expiration for the prepared transaction
`network`	enum	Network for which the transaction was prepared
`recentBlockhash`	string	Recent blockhash used in the transaction
`kind`	enum	Prepared transaction category
`signatureRequests`	array	Embedded `secp256r1` or `secp256k1` signatures to obtain and patch before submission

Each signature request carries scheme, signer, messageHash, slot, and counter. The signer is encoded for its signature scheme, and messageHash is the hex-encoded message to sign. An empty array does not prove that the transaction needs no application signature; inspect the Solana transaction’s required signer set for native Ed25519 authorities and other transaction-level signers.

Rent claimers

These API-key routes read and configure the rent recipient on a V2 Swig. Use the Swig config PDA as swig_address or swigAddress.

Read the recipient

GET /transaction/wallet/{swig_address}/rent-claimer?network=NETWORK_MAINNET network is required and accepts NETWORK_MAINNET or NETWORK_DEVNET. The backend reads finalized chain state and returns:

{ "rentClaimer": "RecipientPublicKey" }

When a valid config has no recipient, the optional rentClaimer field is absent. Missing accounts, malformed or unsupported state, and RPC failures return errors. A requester authority is not needed for this read.

Prepare the setter

POST /transaction/wallet/rent-claimer/set

{
  "network": "NETWORK_MAINNET",
  "feePayer": "FeePayerPublicKey",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": { "publicKey": "RequesterPublicKey" }
  },
  "rentClaimer": "RecipientPublicKey"
}

Every field shown is required. The requester must match a direct Ed25519 role with All or CloseSwigAuthority; ManageAuthority alone is insufficient. The recipient must differ from the zero public key, config PDA, and wallet PDA. An existing recipient is rejected even when it matches the requested value. The response wraps an unsigned prepared transaction:

{
  "transaction": {
    "transaction": "Base64EncodedUnsignedTransaction",
    "transactionEncoding": "TRANSACTION_ENCODING_BASE64",
    "network": "NETWORK_MAINNET",
    "kind": "PREPARED_TRANSACTION_KIND_SET_RENT_CLAIMER",
    "signatureRequests": []
  }
}

Both the requester and fee payer must provide native transaction signatures, or one signature when the keys coincide. The backend fetches finalized state and a fresh blockhash, then prepares the transaction. The application signs, submits, and confirms it. Preparation does not set the recipient; the program enforces the set-once rule when the transaction executes. See Rent Claimers for TypeScript examples.

Prepare a batch

POST /transaction/prepare/batch batches one or more supported operations for an existing Swig.

{
  "network": "NETWORK_DEVNET",
  "feePayer": "FeePayerPublicKey",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": { "publicKey": "RequesterPublicKey" }
  },
  "operations": [
    {
      "transferSol": {
        "destination": "DestinationPublicKey",
        "lamports": "1000000"
      }
    },
    {
      "transferToken": {
        "mint": "MintAddress",
        "destinationOwner": "DestinationOwnerPublicKey",
        "amount": "1000000"
      }
    }
  ]
}

Prepare custom instructions

POST /transaction/prepare/custom builds one prepared Swig transaction from the Solana instructions supplied by the application.

{
  "network": "NETWORK_DEVNET",
  "feePayer": "FeePayerPublicKey",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": { "publicKey": "RequesterPublicKey" }
  },
  "instructions": [
    {
      "programId": "ProgramPublicKey",
      "accounts": [
        {
          "pubkey": "WritableAccountPublicKey",
          "isWritable": true
        }
      ],
      "data": "Base64EncodedInstructionData"
    }
  ],
  "addressLookupTableAccounts": ["LookupTablePublicKey"]
}

The response is prepared only. The application still supplies every embedded signature request and transaction-level signer, then chooses direct or sponsored submission.

Create a wallet

POST /transaction/wallet/create

{
  "network": "NETWORK_DEVNET",
  "feePayer": "FeePayerPublicKey",
  "policyId": "policy_123",
  "initialUser": {
    "ed25519": { "publicKey": "InitialUserPublicKey" }
  }
}

Transfer SOL

POST /transaction/transfer/sol

{
  "network": "NETWORK_DEVNET",
  "feePayer": "FeePayerPublicKey",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": { "publicKey": "RequesterPublicKey" }
  },
  "destination": "DestinationPublicKey",
  "lamports": "1000000"
}

Transfer SPL token

POST /transaction/transfer/spl-token

{
  "network": "NETWORK_DEVNET",
  "feePayer": "FeePayerPublicKey",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": { "publicKey": "RequesterPublicKey" }
  },
  "mint": "MintAddress",
  "destinationOwner": "DestinationOwnerPublicKey",
  "amount": "1000000"
}

Jupiter swap

POST /transaction/swap/jupiter

{
  "network": "NETWORK_DEVNET",
  "feePayer": "FeePayerPublicKey",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": { "publicKey": "RequesterPublicKey" }
  },
  "inputMint": "InputMintAddress",
  "outputMint": "OutputMintAddress",
  "amount": "1000000",
  "slippageBps": 50
}

Optional Jupiter controls:

Field	Type	Purpose
`slippageBps`	number	Maximum slippage in basis points
`wrapAndUnwrapSol`	boolean	Let Jupiter wrap or unwrap native SOL
`tipAmountLamports`	integer string	Optional prioritization tip
`computeUnitPricePercentile`	string	Jupiter compute-unit price percentile
`maxAccounts`	number	Limit the accounts used by the route
`mode`	string	Opaque swap mode forwarded to Jupiter
`blockhashSlotsToExpiry`	number	Requested blockhash lifetime in slots
`destinationAccount`	string	Destination owner; the backend derives the SPL token account, or uses the address for native SOL

Prepare an x402 payment

POST /transaction/payment/x402/prepare prepares a Swig token-payment transaction from a decoded x402 version 2 PaymentRequired challenge. It supports the exact payment scheme on Solana. This route supports Ed25519 and secp256r1 requester authorities only. Decode the resource provider’s PAYMENT-REQUIRED header with your x402 library’s header decoder, or Base64-decode the header value and parse its JSON. Pass the resulting object as paymentRequired.

{
  "paymentRequired": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.example.com/weather"
    },
    "accepts": [
      {
        "scheme": "exact",
        "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
        "amount": "1000",
        "asset": "TokenMintAddress",
        "payTo": "ResourceProviderPublicKey",
        "maxTimeoutSeconds": 300,
        "extra": {
          "feePayer": "FacilitatorPublicKey",
          "memo": "order-123"
        }
      }
    ]
  },
  "network": "NETWORK_DEVNET",
  "swigAddress": "SwigConfigAddress",
  "requesterAuthority": {
    "ed25519": {
      "publicKey": "RequesterPublicKey"
    }
  }
}

Field	Type	Description
`paymentRequired`	object	Decoded x402 version 2 challenge.
`acceptedIndex`	number	Optional zero-based index in `paymentRequired.accepts`.

The selected offer uses:

amount as the payment amount in atomic token units
asset as the token mint address
payTo as the destination owner rather than its token account
extra.feePayer as the facilitator fee payer

An eligible offer must use the exact scheme and the requested Solana network. Its amount must be a canonical positive integer string that fits in an unsigned 64-bit integer. asset, payTo, and extra.feePayer must be valid Solana public keys. extra is required, maxTimeoutSeconds must be a positive unsigned 32-bit integer, and an optional memo must not exceed 256 UTF-8 bytes. The network field inside each offer uses a CAIP-2 identifier. In this example, solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 corresponds to NETWORK_DEVNET in the request’s top-level network field. When acceptedIndex is omitted, Swig selects the first eligible offer on the Solana network specified by the request’s top-level network. With an explicit index, that offer must match the requested network; Swig returns an error instead of selecting another offer. Offer selection evaluates these request fields only. Account and balance validation happens after selection; if that validation fails, Swig does not try the next offer. On success, acceptedIndex is always present, including when the selected offer is at index 0:

{
  "preparedTransaction": {
    "transaction": "Base64EncodedTransaction",
    "transactionEncoding": "TRANSACTION_ENCODING_BASE64",
    "wallet": {
      "swigConfigAddress": "SwigConfigAddress",
      "walletAddress": "SwigWalletAddress"
    },
    "expiresAt": "2026-09-09T12:00:00Z",
    "network": "NETWORK_DEVNET",
    "recentBlockhash": "RecentBlockhash",
    "kind": "PREPARED_TRANSACTION_KIND_X402_PAYMENT",
    "signatureRequests": []
  },
  "acceptedIndex": 0
}

See x402 Payments for decoding the resource response, signing the prepared transaction, creating the PAYMENT-SIGNATURE header, and retrying the protected request.

After preparation

For most prepared transactions, your application supplies every embedded signature request and transaction-level signer, then submits the transactions in the returned order—directly or through the Paymaster API. For x402 payments, sign the prepared transaction, create the PAYMENT-SIGNATURE header, and retry the protected resource request. The resource provider’s facilitator verifies and settles the transaction. If policyId is omitted on wallet creation, initialUser is required and the API creates a wallet policy for the caller’s organization.

Start Here

Runtime APIs

Boundaries

Transaction API

Supported preparation routes

Auth

Common request fields

Prepared transaction response

Rent claimers

Read the recipient

Prepare the setter

Prepare a batch

Prepare custom instructions

Create a wallet

Transfer SOL

Transfer SPL token

Jupiter swap

Prepare an x402 payment

After preparation

​Supported preparation routes

​Auth

​Common request fields

​Prepared transaction response

​Rent claimers

​Read the recipient

​Prepare the setter

​Prepare a batch

​Prepare custom instructions

​Create a wallet

​Transfer SOL

​Transfer SPL token

​Jupiter swap

​Prepare an x402 payment

​After preparation

Supported preparation routes

Auth

Common request fields

Prepared transaction response

Rent claimers

Read the recipient

Prepare the setter

Prepare a batch

Prepare custom instructions

Create a wallet

Transfer SOL

Transfer SPL token

Jupiter swap

Prepare an x402 payment

After preparation