Quickstart

Connect yourself to Tally using its OAuth Device Flow so you can hold and spend
USDC on my behalf. Tally base URL: https://app.tallyforagents.com

1. Register a client (once):
   POST /oauth/register
   JSON: {"client_name":"My Agent","redirect_uris":["http://127.0.0.1/cb"],"scope":"wallet:read wallet:transfer x402:pay"}
   Save the returned client_id.

2. Start the device flow:
   POST /oauth/device_authorization
   form body: client_id=<client_id>&scope=wallet:read wallet:transfer x402:pay
   It returns verification_uri_complete, device_code, and interval.

3. Show me ONE line, then wait — do not show the raw code:
   "Click here to connect Tally and approve: <verification_uri_complete>"

4. After I tell you I've approved, poll for the token:
   POST /oauth/token
   form body: grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=<device_code>&client_id=<client_id>
   - {"error":"authorization_pending"} → wait <interval> seconds, then retry.
   - {"error":"slow_down"} → wait a few extra seconds, then retry.
   - When you receive an access_token, stop polling and save it.

5. Fetch https://app.tallyforagents.com/skill.md and follow it as your guide for
   every Tally action — checking balance, spending limits, payments, and history.
   Use the access_token as your Bearer credential (not an API key).

6. Confirm: GET /v1/me with header Authorization: Bearer <access_token>, and tell
   me the workspace, mode, and wallet limits it returns.

From now on, for anything money- or wallet-related, use the Tally REST endpoints
from that skill — don't invent endpoints.

TALLY_API_KEY=tly_test_…

npm install @tallyforagents/sdk

import { Tally } from "@tallyforagents/sdk";

const tally = new Tally({ apiKey: process.env.TALLY_API_KEY! });

const agent = await tally.agents.upsert({ id: "quickstart-bot" });
console.log(agent.status);
// → "no_permissions"

const payment = await tally.payments.create({
  agent_id: "quickstart-bot",
  wallet: "0xYOUR_WALLET_ADDRESS",
  to: "0xRECIPIENT_ADDRESS",
  amount_usdc: "1.00",
  memo: "quickstart test",
});

console.log(payment.status, payment.tx_hash);
// → "pending" 0xabc...

let p = await tally.payments.get(payment.id);

while (p.status === "pending") {
  await new Promise((r) => setTimeout(r, 2_000));
  p = await tally.payments.get(p.id);
}

console.log(p.status); // → "confirmed" or "failed"