swig-developer-sdk 0.7.0__tar.gz → 0.8.0__tar.gz

swig_developer_sdk-0.8.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+*.tgz
+*.tsbuildinfo
+.env
+.env.*
+!.env.example
+.DS_Store
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+*.egg-info/
+python/dist/
+output/

swig_developer_sdk-0.8.0/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2026 Swig
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

swig_developer_sdk-0.8.0/PKG-INFO

@@ -0,0 +1,538 @@
+Metadata-Version: 2.5
+Name: swig-developer-sdk
+Version: 0.8.0
+Summary: Python SDK for preparing and locally signing Swig wallet transactions
+Project-URL: Repository, https://github.com/anagrambuild/swig-developer-sdk
+Author: Anagram
+License: Copyright 2026 Swig
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+            http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+License-File: LICENSE.txt
+Requires-Python: >=3.10
+Requires-Dist: base58<3,>=2.1
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: solders<0.29,>=0.28
+Description-Content-Type: text/markdown
+
+# swig-developer-sdk
+
+Python SDK for preparing Swig wallet operations on a server and signing them
+locally. The Swig API prepares wallet transactions; this SDK invokes
+application-owned signers and inserts signatures with `solders`. No signing
+material is sent to the API.
+
+- Version: `0.8.0`
+- Source: <https://github.com/anagrambuild/swig-developer-sdk>
+- Default API base URL: `https://api.onswig.com`
+
+```bash
+pip install swig-developer-sdk
+```
+
+This is the Python parity package for `@swig-wallet/developer-sdk`. Every
+client method is `async`; the transport is `httpx`.
+
+## How it works
+
+1. Your server creates a `SwigClient` with an API key.
+2. Your server prepares a wallet operation and receives one or more unsigned
+   transactions.
+3. Your client signs any transaction whose `signature_requests` is non-empty.
+4. Your app submits the transactions in order, directly or through Swig's
+   paymaster sponsorship.
+
+The API key stays on the server. Browser code calls a route in your own app —
+see [Proxy handler](#proxy-handler).
+
+## Create a client
+
+Create an API key from the [Swig dashboard](https://dashboard.onswig.com).
+
+```python
+from swig_developer_sdk import SwigClient
+
+swig = SwigClient(api_key="sk_...", network="devnet")
+```
+
+Requests authenticate with `Authorization: Bearer <api-key>`. Override the base
+URL for non-production deployments:
+
+```python
+from swig_developer_sdk import RetryOptions, SwigClient
+
+swig = SwigClient(
+    api_key="sk_...",
+    base_url="http://localhost:8080",
+    network="devnet",
+    retry_options=RetryOptions(max_retries=3, retry_delay=1.0),
+)
+```
+
+### Retry behavior
+
+- `GET` requests use the configured retry policy.
+- `POST` requests do **not** retry by default, because replaying a preparation
+  or submission request can duplicate work.
+- Sponsorship `POST` requests retry only when `idempotency_key` is set. A
+  matching retry returns the original paymaster response.
+- `4xx` responses raise `SwigDeveloperSdkError` immediately.
+
+## Create a wallet
+
+```python
+created = await swig.wallets.create(
+    fee_payer=fee_payer,
+    initial_user={"ed25519": {"publicKey": user_public_key}},
+)
+```
+
+Use `secp256r1` for a passkey initial user or `secp256k1` for an EVM key. Pass
+`policy_id` to create from a portal policy instead of an inline authority. A
+network is required, either on the call or as the client default.
+
+The result splits the prepared transactions:
+
+| Field | What to do |
+| --- | --- |
+| `wallet` | `swig_config_address`, `wallet_address`, and resolved `network` |
+| `transactions` | submit in this exact order |
+| `client_authority_transactions` | get a client authority signature first |
+| `fee_payer_only_transactions` | send or sponsor without a client authority signature |
+| `creation_transaction` | the create transaction itself |
+
+A prepared transaction needs a client authority signature when
+`signature_requests` is non-empty.
+
+## Attach to an existing wallet
+
+```python
+wallet = swig.wallets.use(
+    "SWIG_CONFIG_ADDRESS",
+    requester_authority={"ed25519": {"publicKey": user_public_key}},
+)
+```
+
+`swig.wallets.use` also accepts a `WalletReference`, and
+`swig.wallets.from_idp_session(session)` builds the same handle from an IdP
+session.
+
+### Prepare transfers and swaps
+
+```python
+prepared = await wallet.transfer.sol(
+    fee_payer=fee_payer,
+    destination=destination,
+    amount=1_000_000,
+)
+
+prepared_token = await wallet.transfer.token(
+    fee_payer=fee_payer,
+    mint=mint,
+    destination_owner=destination_owner,
+    amount=10_000,
+)
+
+prepared_swap = await wallet.swap.jupiter(
+    fee_payer=fee_payer,
+    input_mint=input_mint,
+    output_mint=output_mint,
+    amount=10_000,
+    slippage_bps=100,
+    destination_account=destination_account,
+    wrap_and_unwrap_sol=True,
+)
+```
+
+`wallet.transfer(...)` and `wallet.swap(...)` are callable like their
+TypeScript counterparts; `spl_token` is an alias for `token`.
+
+### Prepare grouped operations
+
+```python
+from swig_developer_sdk import TransferSolOperation, TransferTokenOperation
+
+prepared = await wallet.prepare(
+    fee_payer=fee_payer,
+    operations=(
+        TransferSolOperation(destination=destination, amount=1_000_000),
+        TransferTokenOperation(
+            mint=mint,
+            destination_owner=destination_owner,
+            amount=10_000,
+        ),
+    ),
+)
+```
+
+### Build a custom transaction
+
+```python
+from swig_developer_sdk import SolanaAccountMeta, SolanaInstructionInput
+
+prepared = await wallet.build_transaction(
+    fee_payer=fee_payer,
+    instructions=(
+        SolanaInstructionInput(
+            program_id=program_id,
+            accounts=(SolanaAccountMeta(pubkey=destination, is_writable=True),),
+            data=instruction_data,
+        ),
+    ),
+    address_lookup_table_accounts=(lookup_table_address,),
+)
+```
+
+The returned transaction is still signed and submitted by your application.
+
+## Read wallet state
+
+```python
+usd = await wallet.get_usd_balance()
+# usd.swig_config_address, usd.wallet_address, usd.usd_value
+
+tokens = await wallet.list_token_balances()
+# tokens.balances[].mint_address, asset_kind, ui_amount, usd_value
+
+activity = await wallet.list_token_transactions(limit=25)
+# activity.transactions[].transaction_signature, direction, asset_kind, ui_amount
+```
+
+### Roles
+
+`list_roles()` returns the on-chain roles attached to the Swig, which is how
+you inspect who currently holds authority and what each authority may do.
+
+```python
+result = await wallet.list_roles()
+
+for role in result.roles:
+    print(role.role_id, role.authority_type, role.authority_value)
+    for action in role.actions:
+        print(action.action_index, action.action_code, action.action_data)
+```
+
+`authority_value` is the authority's public key material and `authority_type`
+is the protocol authority type discriminant. `action_data` is the raw
+per-action payload, so read it against the protocol's action definitions rather
+than assuming a fixed shape.
+
+Policy metadata is a separate read:
+
+```python
+policy = await swig.wallets.get_policy(policy_id)
+```
+
+## Fiat ramps
+
+Ramp is split into `swig.ramp.onramp` and `swig.ramp.offramp`. Every ramp call
+requires an `environment` of `"sandbox"` or `"production"`; the SDK encodes it
+as the MELD enum on the wire. Options, quotes, and session creation also require
+`organization_meld_configuration_id`. Quotes additionally require
+`external_customer_id`, `swig_config_address`, and a network (from
+`QuoteRampArgs.network` or the client default).
+
+| Client method | Route |
+| --- | --- |
+| `swig.ramp.onramp.get_options` | `GET /wallet/api/ramp/onramp/options` |
+| `swig.ramp.onramp.quote` | `POST /wallet/api/ramp/onramp/quote` |
+| `swig.ramp.onramp.create_session` | `POST /wallet/api/ramp/onramp/session` |
+| `swig.ramp.onramp.get_session` | `GET /wallet/api/ramp/onramp/session/{session_id}` |
+| `swig.ramp.offramp.get_options` | `GET /wallet/api/ramp/offramp/options` |
+| `swig.ramp.offramp.quote` | `POST /wallet/api/ramp/offramp/quote` |
+| `swig.ramp.offramp.create_session` | `POST /wallet/api/ramp/offramp/session` |
+| `swig.ramp.offramp.prepare_authorization` | `POST /wallet/api/ramp/offramp/session/{session_id}/prepare` |
+| `swig.ramp.offramp.submit_authorization` | `POST /wallet/api/ramp/offramp/session/{session_id}/submit` |
+| `swig.ramp.offramp.get_session` | `GET /wallet/api/ramp/offramp/session/{session_id}` |
+
+### Onramp
+
+```python
+import os
+
+from swig_developer_sdk import QuoteRampArgs
+
+environment = "sandbox"
+configuration_id = os.environ["SWIG_MELD_CONFIG_ID"]
+
+options = await swig.ramp.onramp.get_options(
+    organization_meld_configuration_id=configuration_id,
+    environment=environment,
+    country_code="US",
+)
+
+result = await swig.ramp.onramp.quote(
+    QuoteRampArgs(
+        organization_meld_configuration_id=configuration_id,
+        environment=environment,
+        external_customer_id=external_customer_id,
+        swig_config_address=swig_config_address,
+        network="devnet",
+        source_amount="100.00",
+        source_currency_code=options.fiat_currency_codes[0],
+        destination_currency_code=options.crypto_currency_codes[0],
+        country_code="US",
+        payment_method_type=options.payment_method_types[0],
+    )
+)
+
+session = await swig.ramp.onramp.create_session(
+    organization_meld_configuration_id=configuration_id,
+    quote_id=result.quotes[0].quote_id,
+    environment=environment,
+)
+
+# Send session.launch_url to the user. Treat it as a user-specific secret.
+state = await swig.ramp.onramp.get_session(
+    session_id=session.session_id,
+    environment=environment,
+)
+```
+
+`state.status` is one of `unspecified`, `created`, `pending`, `settling`,
+`settled`, `failed`, `declined`, `cancelled`, or `refunded`.
+
+### Offramp
+
+Offramp adds an on-chain authorization step: the user's wallet must sign the
+transfer to the provider before the session can settle.
+
+```python
+from swig_developer_sdk import QuoteRampArgs, sign_prepared_swig_transaction
+
+options = await swig.ramp.offramp.get_options(
+    organization_meld_configuration_id=configuration_id,
+    environment=environment,
+    country_code="US",
+)
+
+result = await swig.ramp.offramp.quote(
+    QuoteRampArgs(
+        organization_meld_configuration_id=configuration_id,
+        environment=environment,
+        external_customer_id=external_customer_id,
+        swig_config_address=swig_config_address,
+        network="mainnet",
+        source_amount="25.00",
+        source_currency_code=options.crypto_currencies[0].currency_code,
+        destination_currency_code=options.fiat_currency_codes[0],
+        country_code="US",
+        payment_method_type=options.payment_method_types[0],
+    )
+)
+
+session = await swig.ramp.offramp.create_session(
+    organization_meld_configuration_id=configuration_id,
+    quote_id=result.quotes[0].quote_id,
+    environment=environment,
+)
+
+authorization = await swig.ramp.offramp.prepare_authorization(
+    session_id=session.session_id,
+    environment=environment,
+    fee_payer=fee_payer,
+    requester_authority={"secp256r1": {"publicKey": passkey_public_key}},
+)
+
+# Show authorization.display to the user, then sign.
+signed = await sign_prepared_swig_transaction(
+    authorization.prepared_transaction,
+    secp256r1=application_passkey_signer,
+)
+
+submitted = await swig.ramp.offramp.submit_authorization(
+    session_id=session.session_id,
+    environment=environment,
+    authorization_id=authorization.authorization_id,
+    signed_transaction=signed.transaction,
+)
+# submitted.solana_signature
+```
+
+`authorization.display` carries the human-readable transfer summary
+(`source_amount`, `destination_amount`, `service_provider`, wallet addresses,
+and optional `payment_method_type` / `provider_destination_amount`). Offramp
+sessions add `transfer-required` and `transfer-submitted` to the status set.
+
+## Sign locally
+
+The generic signer helper works with an application-owned Ed25519 signer. The
+Swig signer helper patches secp256r1 or secp256k1 signatures into both legacy
+and versioned Solana transactions.
+
+```python
+from swig_developer_sdk import (
+    sign_prepared_swig_transaction,
+    sign_prepared_transaction,
+)
+
+signed = await sign_prepared_transaction(
+    prepared,
+    sign_transaction=application_ed25519_signer,
+)
+
+signed = await sign_prepared_swig_transaction(
+    prepared,
+    secp256r1=application_passkey_signer,
+)
+```
+
+`sign_prepared_swig_transactions(...)` signs an ordered sequence, which is what
+`created.client_authority_transactions` needs.
+
+WebAuthn and EIP-1193 adapters are callback-based, so applications can connect
+a browser, hardware, wallet, or remote signer without changing the preparation
+API:
+
+```python
+from swig_developer_sdk import (
+    create_secp256k1_evm_signing_fn,
+    create_secp256r1_passkey_signing_fn,
+)
+
+passkey_signer = create_secp256r1_passkey_signing_fn(get_webauthn_assertion)
+evm_signer = create_secp256k1_evm_signing_fn(
+    provider=eip1193_provider,
+    address=evm_address,
+)
+```
+
+## Submit and sponsor
+
+```python
+from swig_developer_sdk import SponsorSignedTransactionArgs
+
+submitted = await swig.transactions.sponsor(
+    SponsorSignedTransactionArgs(
+        transaction=signed.transaction,
+        network="mainnet",
+        idempotency_key=idempotency_key,
+    )
+)
+# submitted.request_id, submitted.signature, submitted.spent_by_paymaster
+```
+
+Pass `idempotency_key` whenever your application may retry; that is the only
+case in which the SDK retries a sponsorship POST.
+
+For single-transaction sponsorship, `network` resolves from the call and then
+the client default. If neither is set, the paymaster defaults to mainnet.
+
+A returned signature means the Solana RPC accepted the transaction. It may
+still be pending and is not confirmation or finality; track it through your
+RPC provider when your product needs either.
+
+### Bundle sponsorship
+
+```python
+from swig_developer_sdk import SponsorSignedTransactionBundleArgs
+
+bundle = await swig.transactions.sponsor_bundle(
+    SponsorSignedTransactionBundleArgs(
+        transactions=(signed_create.transaction, signed_add_authority.transaction),
+        network="mainnet",
+        idempotency_key=idempotency_key,
+    )
+)
+# bundle.request_id, bundle.bundle_id, bundle.signatures,
+# bundle.estimated_spent_by_paymaster
+```
+
+Constraints enforced before the request is sent:
+
+- mainnet only — any other network raises `ValueError`
+- one to five transactions per bundle
+- `signatures` come back in bundle order
+- `estimated_spent_by_paymaster` is an estimate, not a settled charge
+
+A returned `bundle_id` means Jito accepted the bundle. It may still be pending;
+acceptance is not confirmation or finality.
+
+## Paymaster balance
+
+```python
+balance = await swig.paymaster.get_balance(network="mainnet")
+idp_balance = await swig.paymaster.get_idp_balance(network="mainnet")
+# balance.configured, balance.address, balance.balance_lamports, balance.balance_sol
+```
+
+## Proxy handler
+
+Python ships a framework-neutral proxy handler instead of one framework
+adapter. Adapt your framework's request and response objects at the route
+boundary:
+
+```python
+from swig_developer_sdk import SwigProxyConfig, create_swig_proxy_handler
+
+swig_handler = create_swig_proxy_handler(
+    SwigProxyConfig(api_key=swig_api_key, network="devnet")
+)
+
+response = await swig_handler.handle(
+    method="POST",
+    path="/transfer/sol",
+    body=request_body,
+)
+# return response.body with response.status
+```
+
+The handler covers the same routes as the TypeScript adapters: wallet create,
+grouped prepare, SOL and SPL transfers, Jupiter swap, wallet USD balance, token
+balances, token transactions, roles, paymaster balance, and the onramp and
+offramp routes.
+
+`SwigProxyConfig` accepts `api_key`, `transaction_api_url`, `network`,
+`fee_payer` (a value or a callable resolved per request),
+`resolve_requester_authority`, and an optional `httpx` transport. It falls back
+to `SWIG_DEVELOPER_API_KEY` / `SWIG_API_KEY`, `SWIG_TRANSACTION_API_URL`, and
+`SWIG_FEE_PAYER` when those fields are unset. A fee payer is required for every
+preparation route; the handler returns a `400` body when it cannot resolve one.
+
+## Errors
+
+```python
+from swig_developer_sdk import SwigDeveloperSdkError
+
+try:
+    await wallet.transfer.sol(
+        fee_payer=fee_payer,
+        destination=destination,
+        amount=1_000_000,
+    )
+except SwigDeveloperSdkError as error:
+    print(error.status_code, error.code, error)
+```
+
+Keep API keys, signed transactions, and ramp launch URLs out of logs.
+
+## Local end-to-end script
+
+`scripts/local_transaction_e2e.py` exercises wallet creation, real P-256
+signing, direct and grouped SOL transfers, an SPL-token transfer, the Python
+proxy, the live paymaster balance endpoint, and a sponsored transfer where the
+user pays no network fee. Every transaction is submitted to Surfpool and
+verified on-chain; the paymaster flow also retries with the same idempotency
+key and verifies that no balance change repeats.
+
+It requires a locally running backend stack, and defaults to
+`http://localhost:8080` for the Developer API and `http://localhost:8899` for
+Surfpool. Override with `SWIG_TRANSACTION_API_URL`, `SOLANA_RPC_URL`, or
+`SWIG_DATABASE_URL`.
+
+Jupiter is not covered by this script, since it needs a mainnet-backed
+Surfpool.
+
+## Parity
+
+See the repository [parity matrix](../PARITY.md) for the complete mapped
+surface against `@swig-wallet/developer-sdk`.