diff --git a/api-reference/activities/claim-earn-fees.mdx b/api-reference/activities/claim-earn-fees.mdx index 74ff1e48..9df26d71 100644 --- a/api-reference/activities/claim-earn-fees.mdx +++ b/api-reference/activities/claim-earn-fees.mdx @@ -1,6 +1,6 @@ --- -title: "Claim Earn fees" -description: "Claim Earn fees through the activity pipeline." +title: "Claim earn fees" +description: "Claim earn fees through the activity pipeline." --- import { Authorizations } from "/snippets/api/authorizations.mdx"; diff --git a/docs.json b/docs.json index 21bd186b..b6feb721 100644 --- a/docs.json +++ b/docs.json @@ -443,6 +443,7 @@ ] }, "features/transaction-management/balances", + "features/transaction-management/transaction-history", "features/transaction-management/fiat-on-ramp", { "group": "Earn", diff --git a/features/transaction-management.mdx b/features/transaction-management.mdx index 5e70458f..7fcbb3ab 100644 --- a/features/transaction-management.mdx +++ b/features/transaction-management.mdx @@ -11,6 +11,7 @@ import SendTxConcepts from "/snippets/shared/send-tx-concepts.mdx"; For implementation guides, see: +- [Transaction history](/features/transaction-management/transaction-history) - Query paginated EVM and Solana transaction history for wallet accounts - [Sending Sponsored EVM Transactions (React)](/features/transaction-management/sending-sponsored-transactions) - Using `@turnkey/react-wallet-kit` - [Sending Sponsored Solana Transactions (React)](/features/transaction-management/sending-sponsored-solana-transactions) - Using `@turnkey/react-wallet-kit` - [Sending Sponsored Transactions](/features/transaction-management/broadcasting) - Using `@turnkey/core` directly \ No newline at end of file diff --git a/features/transaction-management/transaction-history.mdx b/features/transaction-management/transaction-history.mdx new file mode 100644 index 00000000..c5242a02 --- /dev/null +++ b/features/transaction-management/transaction-history.mdx @@ -0,0 +1,95 @@ +--- +title: "Transaction history" +description: "List EVM and Solana transaction history for any wallet account associated with your organization or one of its suborgs." +sidebarTitle: "Transaction history" +mode: "wide" +--- + +Two queries return onchain transaction history for wallet accounts in your organization: [`list_eth_transaction_history`](/api-reference/queries/list-eth-transaction-history) for EVM chains and [`list_sol_transaction_history`](/api-reference/queries/list-sol-transaction-history) for Solana. Full request/response schemas, cURL examples, and SDK snippets can be found in the [API reference](/api-reference/queries/overview). + +## Prerequisites + +- The queried `address` must belong to a **Turnkey wallet account**. Standalone private-key addresses are not supported. +- Pass the network as a CAIP-2 identifier (`caip2`). For Solana, human-readable aliases such as `solana:mainnet` and `solana:devnet` are accepted and normalized to canonical CAIP-2 values by the API. + +## EVM transaction history + +[`list_eth_transaction_history`](/api-reference/queries/list-eth-transaction-history) takes an organization ID, wallet account address, and EVM `caip2` chain ID (for example `eip155:1` for Ethereum mainnet or `eip155:8453` for Base). Supported chains are listed in the API reference. + +Each item in `transactions` is ordered **newest first** and includes: + +- `transactionHash`, `block` (number, hash, RFC 3339 timestamp), and `status` (`CONFIRMED` or `FINALIZED`) +- `from`, optional `to`, and `origin` (for example `TURNKEY` for Turnkey-submitted transactions) +- `fee` with atomic `amount` and `caip19` asset identifier +- `transfers[]` with `direction` (`IN` / `OUT` relative to the queried address), `asset`, atomic `amount`, `counterparty`, and optional `display` strings for UI +- Optional `turnkey` metadata when Turnkey submitted the transaction: `sponsored`, `activityFingerprint`, and `submittedAt` + +Use `transfers[]` for value movement; `to` reflects the transaction destination (such as a called contract) and may differ from transfer counterparties. + +## Solana transaction history + +[`list_sol_transaction_history`](/api-reference/queries/list-sol-transaction-history) uses the same request shape: organization ID, wallet account address, and Solana `caip2` (canonical mainnet/devnet IDs or `solana:mainnet` / `solana:devnet` aliases). + +Solana responses mirror EVM items where applicable, with chain-specific fields: + +- `signature` instead of `transactionHash` +- `feePayer` — the account that paid the transaction fee (first signer in the message) +- `signers[]` — each signer's `address` and whether the account was `writable` in the message + +`transfers`, `fee`, and `turnkey` follow the same semantics as EVM history. + +## Pagination + +Results are cursor-paginated via optional `paginationOptions` (`limit` between 1 and 100, default 10). Each response includes a `pageInfo` block: + +- `hasNextPage` / `hasPreviousPage` indicate whether more results exist in either direction. +- Pass `pageInfo.endCursor` as the next request's `paginationOptions.after` to fetch **older** transactions (continue paging down the newest-first list). +- Pass `pageInfo.startCursor` as `paginationOptions.before` to fetch **newer** transactions. +- Cursors are opaque and valid only for the same `address` and `caip2` query. Do not construct or modify them. + +Example pagination loop with `@turnkey/sdk-server`: + +```typescript +import { Turnkey } from "@turnkey/sdk-server"; + +const client = new Turnkey({ + apiBaseUrl: "https://api.turnkey.com", + apiPublicKey: process.env.API_PUBLIC_KEY!, + apiPrivateKey: process.env.API_PRIVATE_KEY!, + defaultOrganizationId: process.env.ORGANIZATION_ID!, +}).apiClient(); + +let after: string | undefined; + +for (;;) { + const { transactions, pageInfo } = + await client.listEthTransactionHistory({ + organizationId: process.env.ORGANIZATION_ID!, + address: "", + caip2: "eip155:1", + paginationOptions: { + limit: "25", + ...(after ? { after } : {}), + }, + }); + + if (!transactions.length) break; + + // process transactions... + + if (!pageInfo?.hasNextPage || !pageInfo.endCursor) break; + after = pageInfo.endCursor; +} +``` + +For Solana, call `listSolTransactionHistory` with the same pagination pattern. + +## SDK example + +See the [`with-transaction-history`](https://github.com/tkhq/sdk/tree/main/examples/transaction-management/with-transaction-history) example in the SDK repo for runnable EVM and Solana scripts with interactive prompts and multi-page fetching. + +## Next steps + +- [List Eth transaction history](/api-reference/queries/list-eth-transaction-history) and [List Sol transaction history](/api-reference/queries/list-sol-transaction-history) in the API reference +- [Balances](/features/transaction-management/balances) for current asset balances on supported chains +- [Broadcasting transactions](/features/transaction-management/broadcasting) for submitting new transactions through Turnkey diff --git a/public_api.swagger.json b/public_api.swagger.json index bb5a86c8..89c4218a 100644 --- a/public_api.swagger.json +++ b/public_api.swagger.json @@ -1760,8 +1760,8 @@ }, "/public/v1/submit/claim_earn_fees": { "post": { - "summary": "Claim Earn fees", - "description": "Claim Earn fees through the activity pipeline.", + "summary": "Claim earn fees", + "description": "Claim earn fees through the activity pipeline.", "operationId": "ClaimEarnFees", "responses": { "200": { diff --git a/scripts/openapi-gen/openapi.json b/scripts/openapi-gen/openapi.json index 1ff591c4..a85792ef 100644 --- a/scripts/openapi-gen/openapi.json +++ b/scripts/openapi-gen/openapi.json @@ -2160,8 +2160,8 @@ "tags": [ "Earn" ], - "summary": "Claim Earn fees", - "description": "Claim Earn fees through the activity pipeline.", + "summary": "Claim earn fees", + "description": "Claim earn fees through the activity pipeline.", "operationId": "ClaimEarnFees", "requestBody": { "content": {