Skip to content

docs(x402): update upload payment docs with x402 info PE-8786 #80

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
arielmelendez merged 6 commits into from
Dec 17, 2025
Merged

docs(x402): update upload payment docs with x402 info PE-8786 #80

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
414b0e2
docs(x402): update upload payment docs with x402 info PE-8786
Dec 16, 2025
da1b9ac
Merge remote-tracking branch 'origin/main' into PE-8786_x402_upload_p…
Dec 16, 2025
2472a6a
docs(x402): update links and fees PE-8786
Dec 17, 2025
1f06063
docs(x402): a few more x402 details PE-8786
Dec 17, 2025
0da1e27
docs(x402): table formatting PE-8786
Dec 17, 2025
541fe48
Merge remote-tracking branch 'origin/main' into PE-8786_x402_upload_p…
Dec 17, 2025
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
236 changes: 169 additions & 67 deletions content/build/upload/turbo-credits.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,23 @@ description: "Understanding Turbo's credit system for flexible payment options a
---

import {
CreditCard,
Upload,
Bot,
Code,
CreditCard,
FileText,
Tag,
FolderOpen,
Tag,
Upload,
Zap,
} from "lucide-react";

Turbo Credits are the payment medium used by Turbo's upload service, providing a 1:1 conversion from Arweave's native AR token with additional benefits and flexible payment options.
Data storage on Arweave is paid for in Arweave's native [AR](https://www.coingecko.com/en/coins/arweave) token — divisible to the "Winston" (10¹² per AR). Turbo makes paying for data storage on Arweave faster and even simpler via Turbo Credits.

## What are Turbo Credits?

Turbo Credits represent upload power on the Arweave network, divisible down to 1 trillionth of a credit (Winston Credit). Unlike traditional crypto tokens, Turbo Credits cannot be traded, transferred, or exchanged - they exist solely for uploading data to Arweave.
Turbo Credits are the payment medium used by Turbo's upload service, providing a 1:1 representation of upload power on the Arweave network, and enabling precise pricing for uploads of any size.

Unlike traditional crypto tokens, Turbo Credits cannot be traded or exchanged on secondary markets - they exist solely for uploading data to Arweave. However, credit holders can [share their credits](#credit-sharing) with other wallets, enabling organizational and collaborative use cases.

<Callout type="warning">
**Important:** Turbo Credits are non-refundable and cannot be withdrawn or
Expand All @@ -25,70 +29,160 @@ Turbo Credits represent upload power on the Arweave network, divisible down to 1

## How to Purchase Credits

There are two important choices to make when purchasing credits:

1. Pay in either fiat via Stripe or via crypto tokens on a supported network
2. The address of a [supported crypto wallet](#supported-payment-wallets) type to make the primary holder of the credits

When paying in fiat or crypto, the destination wallet address can be one from any [supported crypto wallet](#supported-payment-wallets). It is optional, however, when paying in crypto; the payer wallet is simply used as the default choice in its absence.

### Payment Methods

- **Fiat Currency**: Credit/debit cards or USDC via Stripe
- **Crypto Tokens**: AR, ETH, SOL, POLYGON, ARIO, USDC, KYVE via transfer transactions
- **Spending Wallets**: Ethereum, Solana, Arweave, and Kyve wallets supported

### Supported Tokens & Purchase Methods

| Payment Method | Turbo SDK | Turbo CLI | Turbo API | Turbo App | ArDrive App |
| ---------------------------- | --------- | --------- | --------- | --------- | ----------- |
| **Fiat (credit/debit card)** | ✅ | ✅ | ✅ | ✅ | ✅ |
| **AR** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **ETH** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **ETH (BASE)** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **SOL** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **POLYGON** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **ARIO** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **USDC (ETH)** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **USDC (BASE)** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **USDC (POLYGON)** | ✅ | ✅ | ✅ | ✅ | ❌ |
| **KYVE** | ✅ | ✅ | ✅ | ❌ | ❌ |

<Callout type="info">
**Wallet Compatibility:** When purchasing with cryptocurrencies, credits are
deposited into the wallet described by optional parameter
`turboCreditDestinationAddress`. When not provided, credits will be added to
the signing wallet of the transfer.
</Callout>
Add credits to your wallet and they will be deducted automatically on each upload. For faster payment networks, it's possible to pay [just-in-time](#just-in-time-payments) with each upload.

#### Fiat Payments

Top up any address of a [supported wallet type](#supported-wallet-types) by paying with a credit or debit card via Stripe.

#### Crypto Tokens

Top up any address of a [supported wallet type](#supported-wallet-types) by paying in any of these supported crypto tokens:

### Purchase Options
| Network | Tokens |
| ----------- | -------------- |
| Arweave | [AR](https://www.coingecko.com/en/coins/arweave) |
| AO | [ARIO](https://www.coingecko.com/en/coins/ar-io-network) |
| Base | [ARIO](https://basescan.org/token/0x138746adfA52909E5920def027f5a8dc1C7EfFb6), [ETH](https://www.coingecko.com/en/coins/ethereum), [USDC](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913), [ARIO](https://basescan.org/token/0x138746adfA52909E5920def027f5a8dc1C7EfFb6)|
| Ethereum | [ETH](https://www.coingecko.com/en/coins/ethereum), [USDC](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) |
| Polygon | [POL](https://www.coingecko.com/en/coins/polygon), [USDC](https://polygonscan.com/address/0x3c499c542cef5e3811e1192ce70d8cc03d5c3359) |
| Solana | [SOL](https://www.coingecko.com/en/coins/solana) |
| Cosmos | [KYVE](https://www.coingecko.com/en/coins/kyve-network) |

**Option 1: Turbo App**
### Supported Payment Wallets

- Visit [turbo.ar.io](https://turbo.ar.io)
- Purchase with USD, ARIO, USDC, SOL, ETH, POL, KYVE tokens
- Credits can be purchased for Arweave, Ethereum, Solana, or Kyve native wallet addresses
| Network Type | Signature Types | Supported Wallets |
| ------------ | -------------- | ------------------------------------------------------ |
| Arweave | RSA | JWK Keyfile, [Wander](https://www.wander.app/), [Beacon](https://getbeaconapp.com/) |
| AO | RSA | JWK Keyfile, [Wander](https://www.wander.app/), [Beacon](https://getbeaconapp.com/) |
| AO | ECDSA (secp256k1) | JSON Keystore File, [MetaMask](https://metamask.io/), [Rainbow](https://rainbow.me/), [Brave](https://brave.com/wallet/), [WalletConnect](https://walletconnect.com/), [Privy](https://www.privy.io/) |
| EVM | ECDSA (secp256k1) | JSON Keystore File, [MetaMask](https://metamask.io/), [Rainbow](https://rainbow.me/), [Brave](https://brave.com/wallet/), [WalletConnect](https://walletconnect.com/), [Privy](https://www.privy.io/) |
| Solana | ED25519 | JSON Keypair File, [Phantom](https://phantom.com/), [Solflare](https://www.solflare.com/) |
| Cosmos | secp256k1 | Keyfile |

**Option 2: ArDrive App**
### Purchasing Interfaces

- Use [ArDrive](https://app.ardrive.io) for simple purchases
- Buy credits with USD directly in the app
- Perfect for occasional users
#### Turbo App

**Option 3: Turbo SDK/CLI**
Visit [turbo.ar.io](https://turbo.ar.io) to purchase credits with fiat or crypto using a connected wallet.

#### ArDrive App

Visit [app.ardrive.io](https://app.ardrive.io) to purchase credits with fiat for Arweave wallets.

#### Turbo Typescript SDK

```js
// Purchase credits programmatically
const { winc, status, id, ...fundResult } = await TurboFactory.authenticated({
signer,
token: "base-usdc",
}).topUpWithTokens({
tokenAmount: USDCToTokenAmount(1), // 1 USDC on base network
turboCreditDestinationAddress:
"any-valid-evm-arweave-solana-kyve-native-wallet-address",
import { TurboFactory, USDCToTokenAmount } from "@ardrive/turbo-sdk";

const turbo = TurboFactory.authenticated({ signer, token: "base-usdc" });

// Top up with crypto
const result = await turbo.topUpWithTokens({
tokenAmount: USDCToTokenAmount(1),
destinationAddress: "optional-different-wallet-address",
});

// Check your balance
const balance = await turbo.getBalance();
console.log(`Balance: ${balance.winc} Winston Credits`);
// Check balance
const { winc } = await turbo.getBalance();
```

See the [Turbo SDK documentation](/sdks/turbo-sdk) and [GitHub repository](https://github.com/ardriveapp/turbo-sdk) for complete examples.

#### Turbo CLI

```bash
# Top up with crypto
turbo top-up --token base-usdc --amount 1

# Check balance
turbo balance
```

See the [Turbo Node.js CLI documentation](https://github.com/ardriveapp/turbo-sdk/?tab=readme-ov-file#cli) for installation and usage.

#### HTTP API

Direct API integration is available at [payment.ardrive.io/api-docs](https://payment.ardrive.io/api-docs) for custom implementations.

#### Payment Interfaces By Token

| Payment Method | Turbo SDK | Turbo CLI | Turbo API | Turbo App | ArDrive App | x402 |
| ---------------------------- | --------- | --------- | --------- | --------- | ----------- | ---- |
| **Fiat (credit/debit card)** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| **AR** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **ETH (L1)** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **ETH (Base)** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **SOL** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **POL** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **ARIO (AO)** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **ARIO (Base)** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **USDC (L1)** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **USDC (Base)** | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| **USDC (Polygon)** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| **KYVE** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |

## Just-in-Time Payments

Just-in-time (JIT) payments allow you to pay for uploads at the moment of upload rather than pre-funding a credit balance. This is ideal for agentic workflows, automated pipelines, and systems that prefer pay-per-upload over balance management.

JIT payments are available via the Turbo SDK, CLI, or direct HTTP API integration for tokens with sufficiently fast confirmation times:

| Token / Currency | Network | JIT Supported |
| ---------------------- | -------- | ------------- |
| ARIO | AO | ✅ |
| ARIO | Base | ✅ |
| SOL | Solana | ✅ |
| ETH | Base | ✅ |
| USDC | Base | ✅ |
| POL | Polygon | ✅ |
| USDC | Polygon | ✅ |
| AR | Arweave | ❌ |
| ETH | L1 | ❌ |
| KYVE | Cosmos | ❌ |
| Fiat | Stripe | ❌ |

### x402 Protocol

[x402](https://www.x402.org/) is a protocolized approach to JIT payments that leverages the HTTP 402 "Payment Required" status code. Turbo currently supports x402 payments made in **USDC on Base**. The following Turbo features can utilize x402:

<Callout type="warning">
**Note:** x402 facilitator fees may be applicable for each x402 payment.
</Callout>

- **Uploads:** pay for storage at the time of upload
- **Top up:** useful when x402 is the preferred payment medium, but facilitator fees on individual uploads are undesirable

Example SDK usage:

```js
import { TurboFactory, X402Funding } from "@ardrive/turbo-sdk";

const turbo = TurboFactory.authenticated({ signer, token: "base-usdc" });

const result = await turbo.uploadFile({
fileStreamFactory: () => fs.createReadStream("./myfile.jpg"),
fileSizeFactory: () => fs.statSync("./myfile.jpg").size,
fundingMode: new X402Funding({ maxMUSDCAmount: 1_000_000 }), // Max 1 USDC
});
```

See the [Turbo SDK documentation](/sdks/turbo-sdk) and [HTTP API docs](https://payment.ardrive.io/api-docs) for complete integration details.

## Credit Sharing

Turbo Credits can be shared with other users without transferring ownership, perfect for organizations and teams.
Turbo Credits can be shared with other users to fund their uploads while maintaining total control over who may spend them, how many they may spend, and for how long they can do so. This is perfect for organizations, collaborations, and teams.

Credits can be shared via the Turbo App at [turbo.ar.io](https://turbo.ar.io) or programmatically via the [Turbo CLI](https://github.com/ardriveapp/turbo-sdk/?tab=readme-ov-file#cli), [SDK](/sdks/turbo-sdk), or [API](https://payment.ardrive.io/api-docs).

### How Credit Sharing Works

Expand All @@ -104,17 +198,20 @@ Turbo Credits can be shared with other users without transferring ownership, per
- **Collaboration**: Share credits with project contributors
- **Educational Programs**: Provide students with controlled access

<Callout type="info">
**Perfect for:** Companies, teams, educational institutions, and any
organization needing controlled access to upload power.
</Callout>

## Pricing & Fees

- **23.4% fee** applied to credit purchases (covers infrastructure and benefits)
- **No additional fees** when using credits for uploads
- **Same value per GiB** as AR regardless of price fluctuations
- **Subsidized uploads** under 100 KiB are completely free
- Turbo top up fees cover the costs of managing infrastructure and, in the case of crypto-based top ups, token liquidity.
- No additional fees are applied when credits are spent.
- Credits maintain a 1:1 peg of storage purchasing power as Arweave's data storage rates and token price fluctuate.
- **Uploads under 100 KiB are completely free and do not require a prior top up.**


| Currency | Top Up Fee Percentage |
| ----------------- | --------------------- |
| ARIO (AO or Base) | NO FEE |
| KYVE | 50% |
| All others | 23.4% |


## Getting Started

Expand All @@ -138,12 +235,17 @@ Ready to start using Turbo Credits? Choose your path:
Learn how to upload data with your new credits
</Card>

<Card
href="/sdks/turbo-sdk"
title="Turbo SDK"
icon={<Code />}
{" "}
<Card href="/sdks/turbo-sdk" title="Turbo SDK" icon={<Code />}>
Integrate credit sharing and advanced features
</Card>

<Card
href="#just-in-time-payments"
title="Just-in-Time Payments"
icon={<Zap />}
>
Integrate credit sharing and advanced features
Pay-per-upload for automated workflows
</Card>
</Cards>

Expand Down