Give an Agent a Budget

const [{ winc: perUpload }] = await turbo.getUploadCosts({ bytes: [6 * 1024 * 1024] });
const cap = BigInt(perUpload) * 10n * 12n / 10n; // ten uploads of 6 MiB, plus 20%

const approval = await turbo.shareCredits({
  approvedAddress: agentAddress,
  approvedWincAmount: cap.toString(),
  expiresBySeconds: 60 * 60 * 24, // one day
});

{
  "approvalDataItemId": "<the signed data item that created the approval>",
  "payingAddress": "<your address>",
  "approvedAddress": "<the agent's address>",
  "approvedWincAmount": "<the cap>",
  "usedWincAmount": "0",
  "creationDate": "<ISO timestamp>",
  "expirationDate": "<ISO timestamp, or absent when there is no expiry>"
}

const { givenApprovals } = await turbo.getCreditShareApprovals({ userAddress: myAddress });
for (const a of givenApprovals) {
  console.log(a.approvedAddress, a.usedWincAmount, "of", a.approvedWincAmount, "expires", a.expirationDate);
}

await turbo.revokeCredits({ revokedAddress: agentAddress });

const size = fs.statSync(path).size;
const { receivedApprovals } = await turbo.getBalance();
const [{ winc: price }] = await turbo.getUploadCosts({ bytes: [size] });
const remaining = receivedApprovals
  .filter((a) => a.payingAddress === funderAddress)
  .reduce((sum, a) => sum + BigInt(a.approvedWincAmount) - BigInt(a.usedWincAmount), 0n);
if (BigInt(price) > remaining) throw new Error("stop: this upload is over the remaining budget");

const receipt = await turbo.uploadFile({
  fileStreamFactory: () => fs.createReadStream(path),
  fileSizeFactory: () => size,
  dataItemOpts: {
    tags: [{ name: "Content-Type", value: "application/octet-stream" }],
    paidBy: [funderAddress],
  },
});

Content-Type: application/json; charset=utf-8
X-Free-Tier-Exhausted: true
X-Payment-Required: x402-1

{"x402Version":1,"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"440164","resource":"https://upload.services.ar-io.dev/v1/tx", ...}]}

import { TurboFactory, X402Funding } from "@ardrive/turbo-sdk";
const turbo = TurboFactory.authenticated({ privateKey, token: "base-usdc" });
await turbo.upload({
  data,
  fundingMode: new X402Funding({ maxMUSDCAmount: 1_000_000 }), // at most 1 USDC for this upload
});

// Share a capped, expiring credit budget with an agent's address, list it, or revoke it.
// Usage: KEYFILE=./funder.json node fund-agent.mjs share <agentAddress> <bytesPerUpload> <uploads>
//        KEYFILE=./funder.json node fund-agent.mjs list
//        KEYFILE=./funder.json node fund-agent.mjs revoke <agentAddress>
import fs from "node:fs";
import { TurboFactory, HexSolanaSigner } from "@ardrive/turbo-sdk";
import bs58 from "bs58";

const sandbox = process.env.SANDBOX === "1";
const secretKey = Uint8Array.from(JSON.parse(fs.readFileSync(process.env.KEYFILE, "utf8")));
const turbo = TurboFactory.authenticated({
  signer: new HexSolanaSigner(bs58.encode(secretKey)),
  token: "solana",
  ...(sandbox && {
    gatewayUrl: "https://api.devnet.solana.com",
    uploadServiceConfig: { url: "https://upload.services.ar-io.dev" },
    paymentServiceConfig: { url: "https://payment.services.ar-io.dev" },
  }),
});

const myAddress = bs58.encode(secretKey.subarray(32));
const [action, agentAddress, bytes, uploads] = process.argv.slice(2);

if (action === "share") {
  const [{ winc: perUpload }] = await turbo.getUploadCosts({ bytes: [Number(bytes)] });
  const cap = (BigInt(perUpload) * BigInt(uploads) * 12n) / 10n; // plus 20% for fees
  const { winc } = await turbo.getBalance();
  if (cap > BigInt(winc)) throw new Error(`stop: cap ${cap} is over the ${winc} winc you can spend`);
  const approval = await turbo.shareCredits({
    approvedAddress: agentAddress,
    approvedWincAmount: cap.toString(),
    expiresBySeconds: 60 * 60 * 24,
  });
  console.log(JSON.stringify(approval, null, 2));
} else if (action === "list") {
  const { givenApprovals } = await turbo.getCreditShareApprovals({ userAddress: myAddress });
  console.log(JSON.stringify(givenApprovals, null, 2));
} else if (action === "revoke") {
  const revoked = await turbo.revokeCredits({ revokedAddress: agentAddress });
  console.log(JSON.stringify(revoked, null, 2));
} else {
  throw new Error("usage: share <agentAddress> <bytesPerUpload> <uploads> | list | revoke <agentAddress>");
}

// Upload one file on a funder's credit share. Stops before the upload when its list price is over what is left.
// Usage: KEYFILE=./agent.json FUNDER=<funderAddress> node agent-upload.mjs ./file.bin
import fs from "node:fs";
import { TurboFactory, HexSolanaSigner } from "@ardrive/turbo-sdk";
import bs58 from "bs58";

const sandbox = process.env.SANDBOX === "1";
const path = process.argv[2];
const funder = process.env.FUNDER;
if (!path || !funder) throw new Error("give the file as the first argument and the funder's address in FUNDER");

const secretKey = Uint8Array.from(JSON.parse(fs.readFileSync(process.env.KEYFILE, "utf8")));
const turbo = TurboFactory.authenticated({
  signer: new HexSolanaSigner(bs58.encode(secretKey)),
  token: "solana",
  ...(sandbox && {
    gatewayUrl: "https://api.devnet.solana.com",
    uploadServiceConfig: { url: "https://upload.services.ar-io.dev" },
    paymentServiceConfig: { url: "https://payment.services.ar-io.dev" },
  }),
});

// 1. Budget check. The agent's own balance is zero by design; the approval is what pays.
const size = fs.statSync(path).size;
const [{ winc: price }] = await turbo.getUploadCosts({ bytes: [size] });
const { receivedApprovals } = await turbo.getBalance();
const remaining = receivedApprovals
  .filter((a) => a.payingAddress === funder)
  .reduce((sum, a) => sum + BigInt(a.approvedWincAmount) - BigInt(a.usedWincAmount), 0n);
console.log(JSON.stringify({ size, price, remaining: remaining.toString() }));
if (BigInt(price) > remaining) {
  throw new Error("stop: over the remaining budget; report what is left and wait for the funder");
}

// 2. Upload against the approval. Keep the receipt.
let receipt;
try {
  receipt = await turbo.uploadFile({
    fileStreamFactory: () => fs.createReadStream(path),
    fileSizeFactory: () => size,
    dataItemOpts: {
      tags: [{ name: "Content-Type", value: "application/octet-stream" }],
      paidBy: [funder],
    },
  });
} catch (e) {
  if (e.status === 402) {
    throw new Error("stop: the approval cannot pay for this item; do not pay the x402 offer; report to the funder");
  }
  throw e;
}
fs.writeFileSync(`${path}.receipt.json`, JSON.stringify(receipt, null, 2));
console.log(JSON.stringify({ id: receipt.id, winc: receipt.winc, paidBy: funder }));

$ node fund-agent.mjs share <agent> 5347738 1
{ "approvedWincAmount": "83100467793", "usedWincAmount": "0", "expirationDate": "2026-10-10T04:16:13.438Z", ... }

$ node agent-upload.mjs ./a.bin
{"size":5347738,"price":"69250389828","remaining":"83100467793"}
{"id":"W5_xhak5tI9HKRqr6u376ZBZaAq0HYef0UPbRmSGCww","winc":"69252409803","paidBy":"<funder>"}

$ node agent-upload.mjs ./b.bin
{"size":5347738,"price":"69250389828","remaining":"13848057990"}
Error: stop: over the remaining budget; report what is left and wait for the funder

$ node fund-agent.mjs list
[ { "approvedWincAmount": "83100467793", "usedWincAmount": "69252409803", ... } ]

$ node fund-agent.mjs revoke <agent>
[ { "usedWincAmount": "69252409803", "inactiveReason": "revoked", ... } ]

$ node agent-upload.mjs ./c.bin
{"size":5347738,"price":"69250389828","remaining":"0"}
Error: stop: over the remaining budget; report what is left and wait for the funder