Skip to content

Sync docs for swap/earn GA #812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moe-dev merged 1 commit into from
Sep 4, 2026
Merged

Sync docs for swap/earn GA #812

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions api-reference/activities/broadcast-evm-transaction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Unique identifier for a given Organization.
</NestedParam>

<NestedParam parentKey="parameters" childKey="caip2" type="enum<string>" required={true} default="">
Enum options: `eip155:1`, `eip155:11155111`, `eip155:8453`, `eip155:84532`, `eip155:137`, `eip155:80002`, `eip155:56`, `eip155:97`, `eip155:10`, `eip155:11155420`, `eip155:143`, `eip155:10143`, `eip155:42161`, `eip155:4217`, `eip155:42431`, `eip155:421614`
Enum options: `eip155:1`, `eip155:11155111`, `eip155:8453`, `eip155:84532`, `eip155:137`, `eip155:80002`, `eip155:56`, `eip155:97`, `eip155:10`, `eip155:11155420`, `eip155:143`, `eip155:10143`, `eip155:42161`, `eip155:4217`, `eip155:42431`, `eip155:421614`, `eip155:4663`, `eip155:46630`
</NestedParam>

<NestedParam parentKey="parameters" childKey="sponsor" type="boolean" required={false} default="">
Expand Down Expand Up @@ -122,7 +122,7 @@ A wallet or private key address to sign with. This does not support private key
<NestedParam parentKey="activity.intent.ethSendTransactionIntentV2" childKey="caip2" type="enum" required={true}>
CAIP-2 chain ID (e.g., 'eip155:1' for Ethereum mainnet).

Enum options: `eip155:1`, `eip155:11155111`, `eip155:8453`, `eip155:84532`, `eip155:137`, `eip155:80002`, `eip155:56`, `eip155:97`, `eip155:10`, `eip155:11155420`, `eip155:143`, `eip155:10143`, `eip155:42161`, `eip155:4217`, `eip155:42431`, `eip155:421614`
Enum options: `eip155:1`, `eip155:11155111`, `eip155:8453`, `eip155:84532`, `eip155:137`, `eip155:80002`, `eip155:56`, `eip155:97`, `eip155:10`, `eip155:11155420`, `eip155:143`, `eip155:10143`, `eip155:42161`, `eip155:4217`, `eip155:42431`, `eip155:421614`, `eip155:4663`, `eip155:46630`

</NestedParam>
<NestedParam parentKey="activity.intent.ethSendTransactionIntentV2" childKey="sponsor" type="boolean" required={false}>
Expand Down
34 changes: 19 additions & 15 deletions api-reference/activities/execute-swap.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,38 +100,41 @@ The activity type
<NestedParam parentKey="activity" childKey="intent" type="object" required={true}>
The intent of the activity
<Expandable title="intent details">
<NestedParam parentKey="activity.intent" childKey="executeSwapIntentV2" type="object" required={true}>
The executeSwapIntentV2 object
<Expandable title="executeSwapIntentV2 details">
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="quoteId" type="string" required={true}>
<NestedParam parentKey="activity.intent" childKey="executeSwapIntentV3" type="object" required={true}>
The executeSwapIntentV3 object
Comment on lines 100 to +104
<Expandable title="executeSwapIntentV3 details">
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="quoteId" type="string" required={true}>
Quote identifier returned by create_swap_quote. Execution is bound to this quote; the signer is derived from the quote and must not be resupplied.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="inputToken" type="string" required={true}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="inputToken" type="string" required={true}>
CAIP-19 asset ID for the input asset.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="inputAmount" type="string" required={true}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="inputAmount" type="string" required={true}>
Exact base-unit amount of the input asset committed by the quote.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="outputToken" type="string" required={true}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="outputToken" type="string" required={true}>
CAIP-19 asset ID for the output asset.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="quotedOutputAmount" type="string" required={true}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="quotedOutputAmount" type="string" required={true}>
Exact quoted base-unit output amount committed by the quote.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="minOutputAmount" type="string" required={true}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="minOutputAmount" type="string" required={true}>
Exact minimum base-unit output committed by the quote.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="sponsor" type="boolean" required={true}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="sponsor" type="boolean" required={true}>
Whether the quoted transaction is sponsored.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="evmNonce" type="string" required={false}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="evmNonce" type="string" required={false}>
Exact EVM sender (EOA account) nonce. Valid only for a non-sponsored EVM swap. Honored for already-delegated (Type-2) batch swaps and single-call swaps; ignored for not-yet-delegated EIP-7702 (Type-4) batches where the outer nonce is derived from the authorization. Prefer gas_station_nonce for batch replay protection and use the nonces endpoint to fetch it. Omit to auto-fetch.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="recentBlockhash" type="string" required={false}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="recentBlockhash" type="string" required={false}>
Exact Solana recent blockhash. Valid only for a Solana swap, including sponsored swaps. Omit to auto-fetch.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV2" childKey="gasStationNonce" type="string" required={false}>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="gasStationNonce" type="string" required={false}>
Exact gas station delegate contract nonce used in the BatchExecution EIP-712 message. Valid for sponsored EVM swaps and non-sponsored EVM swaps that execute as a multi-call batch (for example ERC-20 approve + swap). This is the replay-protection nonce for gas-station batches; use the nonces endpoint to fetch it. Omit to auto-fetch.
</NestedParam>
<NestedParam parentKey="activity.intent.executeSwapIntentV3" childKey="destinationAddress" type="string" required={false}>
Raw public address that receives the output asset. Required for cross-protocol swaps. The address must match the output token protocol. Wallet account IDs, private key IDs, and CAIP account or asset identifiers are not supported.
</NestedParam>

</Expandable>
Expand Down Expand Up @@ -252,7 +255,7 @@ const response = await turnkeyClient.apiClient().executeSwap({
"status": "<string>",
"type": "<string>",
"intent": {
"executeSwapIntentV2": {
"executeSwapIntentV3": {
"quoteId": "<string>",
"inputToken": "<string>",
"inputAmount": "<string>",
Expand All @@ -262,7 +265,8 @@ const response = await turnkeyClient.apiClient().executeSwap({
"sponsor": "<boolean>",
"evmNonce": "<string>",
"recentBlockhash": "<string>",
"gasStationNonce": "<string>"
"gasStationNonce": "<string>",
"destinationAddress": "<string>"
}
},
"result": {
Expand Down
26 changes: 15 additions & 11 deletions api-reference/activities/get-swap-quote.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,23 +80,26 @@ The activity type
<NestedParam parentKey="activity" childKey="intent" type="object" required={true}>
The intent of the activity
<Expandable title="intent details">
<NestedParam parentKey="activity.intent" childKey="createSwapQuoteIntent" type="object" required={true}>
The createSwapQuoteIntent object
<Expandable title="createSwapQuoteIntent details">
<NestedParam parentKey="activity.intent.createSwapQuoteIntent" childKey="signWith" type="string" required={true}>
Wallet account or Private Key address used to price the executable provider quote. Private Key identifiers are not supported.
<NestedParam parentKey="activity.intent" childKey="createSwapQuoteIntentV2" type="object" required={true}>
The createSwapQuoteIntentV2 object
<Expandable title="createSwapQuoteIntentV2 details">
<NestedParam parentKey="activity.intent.createSwapQuoteIntentV2" childKey="signWith" type="string" required={true}>
Wallet account address used to price the executable provider quote. Private Key identifiers are not supported.
</NestedParam>
<NestedParam parentKey="activity.intent.createSwapQuoteIntent" childKey="inputToken" type="string" required={true}>
<NestedParam parentKey="activity.intent.createSwapQuoteIntentV2" childKey="inputToken" type="string" required={true}>
CAIP-19 asset ID for the input asset. The chain is derived from this value.
Comment on lines +83 to 90
</NestedParam>
<NestedParam parentKey="activity.intent.createSwapQuoteIntent" childKey="outputToken" type="string" required={true}>
<NestedParam parentKey="activity.intent.createSwapQuoteIntentV2" childKey="outputToken" type="string" required={true}>
CAIP-19 asset ID for the output asset.
</NestedParam>
<NestedParam parentKey="activity.intent.createSwapQuoteIntent" childKey="inputAmount" type="string" required={true}>
<NestedParam parentKey="activity.intent.createSwapQuoteIntentV2" childKey="inputAmount" type="string" required={true}>
Base-unit amount of the input asset.
</NestedParam>
<NestedParam parentKey="activity.intent.createSwapQuoteIntent" childKey="slippageBps" type="string" required={false}>
<NestedParam parentKey="activity.intent.createSwapQuoteIntentV2" childKey="slippageBps" type="string" required={false}>
Provider-neutral maximum allowed slippage in basis points. Turnkey converts this value to each provider's request format. When omitted, each provider applies its default slippage behavior.
</NestedParam>
<NestedParam parentKey="activity.intent.createSwapQuoteIntentV2" childKey="destinationAddress" type="string" required={false}>
Raw public address that receives the output asset. Required for cross-protocol swaps. The address must match the output token protocol. Wallet account IDs, private key IDs, and CAIP account or asset identifiers are not supported.
</NestedParam>

</Expandable>
Expand Down Expand Up @@ -228,12 +231,13 @@ const response = await turnkeyClient.apiClient().createSwapQuote({
"status": "<string>",
"type": "<string>",
"intent": {
"createSwapQuoteIntent": {
"createSwapQuoteIntentV2": {
"signWith": "<string>",
"inputToken": "<string>",
"outputToken": "<string>",
"inputAmount": "<string>",
"slippageBps": "<string>"
"slippageBps": "<string>",
"destinationAddress": "<string>"
}
},
"result": {
Expand Down
205 changes: 205 additions & 0 deletions api-reference/activities/init-import-secrets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
---
title: "Init import secrets"
description: "Initialize secret imports by generating Ingress Encryption Target Keys."
---

import { Authorizations } from "/snippets/api/authorizations.mdx";
import { H3Bordered } from "/snippets/h3-bordered.mdx";
import { NestedParam } from "/snippets/nested-param.mdx";
import { EndpointPath } from "/snippets/api/endpoint.mdx";

<EndpointPath type="submit" path="init_import_secrets" />

<Authorizations />

<H3Bordered text="Body" />

<ParamField body="type" type="enum<string>" required={true}>

Enum options: `ACTIVITY_TYPE_INIT_IMPORT_SECRETS`
</ParamField>

<ParamField body="timestampMs" type="string" required={true}>

Timestamp (in milliseconds) of the request, used to verify liveness of user requests.
</ParamField>

<ParamField body="organizationId" type="string" required={true}>

Unique identifier for a given Organization.
</ParamField>

<ParamField body="parameters" type="object" required={true} path="parameters">
<p>The parameters object containing the specific intent data for this activity.</p>
<Expandable title="details">
<NestedParam parentKey="parameters" childKey="encryptionSuite" type="enum<string>" required={true} default="">
Enum options: `TRANSPORT_ENCRYPTION_SUITE_ENCLAVE_ENCRYPT_V1`
</NestedParam>

<NestedParam parentKey="parameters" childKey="numSecrets" type="number" required={true} default="">
The number of secrets the user intends to import.
</NestedParam>
</Expandable>
</ParamField>

<H3Bordered text="Response" />
A successful response returns the following fields:

<ResponseField name="activity" type="object" required={true}>
The activity object containing type, intent, and result
<Expandable title="activity details">
<NestedParam parentKey="activity" childKey="id" type="string" required={true}>
Unique identifier for a given Activity object.
</NestedParam>
<NestedParam parentKey="activity" childKey="organizationId" type="string" required={true}>
Unique identifier for a given Organization.
</NestedParam>
<NestedParam parentKey="activity" childKey="status" type="string" required={true}>
The activity status
</NestedParam>
<NestedParam parentKey="activity" childKey="type" type="string" required={true}>
The activity type
</NestedParam>
<NestedParam parentKey="activity" childKey="intent" type="object" required={true}>
The intent of the activity
<Expandable title="intent details">
<NestedParam parentKey="activity.intent" childKey="initImportSecretsIntent" type="object" required={true}>
The initImportSecretsIntent object
<Expandable title="initImportSecretsIntent details">
<NestedParam parentKey="activity.intent.initImportSecretsIntent" childKey="encryptionSuite" type="enum" required={true}>
encryptionSuite field

Enum options: `TRANSPORT_ENCRYPTION_SUITE_ENCLAVE_ENCRYPT_V1`

</NestedParam>
<NestedParam parentKey="activity.intent.initImportSecretsIntent" childKey="numSecrets" type="number" required={true}>
The number of secrets the user intends to import.
</NestedParam>

</Expandable>
</NestedParam>

</Expandable>
</NestedParam>
<NestedParam parentKey="activity" childKey="result" type="object" required={true}>
The result of the activity
<Expandable title="result details">
<NestedParam parentKey="activity.result" childKey="initImportSecretsResult" type="object" required={true}>
The initImportSecretsResult object
<Expandable title="initImportSecretsResult details">
<NestedParam parentKey="activity.result.initImportSecretsResult" childKey="enclaveTargetMessages" type="array" required={true}>
Enclave ingress target keys along with metadata specific to the encryption suite. For enclave encrypt v1 this will be ServerTargetMsgV1.
<Expandable title="enclaveTargetMessages details">
<NestedParam parentKey="activity.result.initImportSecretsResult.enclaveTargetMessages" childKey="item" type="string" required={true}>
item field
</NestedParam>

</Expandable>
</NestedParam>

</Expandable>
</NestedParam>

</Expandable>
</NestedParam>
<NestedParam parentKey="activity" childKey="votes" type="array" required={true}>
A list of objects representing a particular User's approval or rejection of a Consensus request, including all relevant metadata.
</NestedParam>
<NestedParam parentKey="activity" childKey="fingerprint" type="string" required={true}>
An artifact verifying a User's action.
</NestedParam>
<NestedParam parentKey="activity" childKey="canApprove" type="boolean" required={true}>
Whether the activity can be approved.
</NestedParam>
<NestedParam parentKey="activity" childKey="canReject" type="boolean" required={true}>
Whether the activity can be rejected.
</NestedParam>
<NestedParam parentKey="activity" childKey="createdAt" type="string" required={true}>
The creation timestamp.
</NestedParam>
<NestedParam parentKey="activity" childKey="updatedAt" type="string" required={true}>
The last update timestamp.
</NestedParam>

</Expandable>
</ResponseField>

<RequestExample>

```bash title="cURL"
curl --request POST \
--url https://api.turnkey.com/public/v1/submit/init_import_secrets \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "X-Stamp: <string> (see Authorizations)" \
--data '{
"type": "ACTIVITY_TYPE_INIT_IMPORT_SECRETS",
"timestampMs": "<string> (e.g. 1746736509954)",
"organizationId": "<string> (Your Organization ID)",
"parameters": {
"encryptionSuite": "<TRANSPORT_ENCRYPTION_SUITE_ENCLAVE_ENCRYPT_V1>",
"numSecrets": "<number>"
}
}'
```

```javascript title="JavaScript"
import { Turnkey } from "@turnkey/sdk-server";

const turnkeyClient = new Turnkey({
apiBaseUrl: "https://api.turnkey.com",
apiPublicKey: process.env.API_PUBLIC_KEY!,
apiPrivateKey: process.env.API_PRIVATE_KEY!,
defaultOrganizationId: process.env.ORGANIZATION_ID!,
});

const response = await turnkeyClient.apiClient().initImportSecrets({
encryptionSuite: "<TRANSPORT_ENCRYPTION_SUITE_ENCLAVE_ENCRYPT_V1>" // encryptionSuite field,
numSecrets: 0 // The number of secrets the user intends to import.
});
Comment on lines +156 to +159
```

</RequestExample>

<ResponseExample>

```json 200
{
"activity": {
"id": "<activity-id>",
"status": "ACTIVITY_STATUS_COMPLETED",
"type": "ACTIVITY_TYPE_INIT_IMPORT_SECRETS",
"organizationId": "<organization-id>",
"timestampMs": "<timestamp> (e.g. 1746736509954)",
"result": {
"activity": {
"id": "<string>",
"organizationId": "<string>",
"status": "<string>",
"type": "<string>",
"intent": {
"initImportSecretsIntent": {
"encryptionSuite": "<TRANSPORT_ENCRYPTION_SUITE_ENCLAVE_ENCRYPT_V1>",
"numSecrets": "<number>"
}
},
"result": {
"initImportSecretsResult": {
"enclaveTargetMessages": [
"<string>"
]
}
},
"votes": "<array>",
"fingerprint": "<string>",
"canApprove": "<boolean>",
"canReject": "<boolean>",
"createdAt": "<string>",
"updatedAt": "<string>"
}
}
}
}
```

</ResponseExample>
Loading