SDK reference
Current BaseAgent configuration, lifecycle methods, result types, and failure handling.
Use the repository build
Build with npm --prefix packages/sdk run build from the repository root. The CommonJS entry is packages/sdk/dist/packages/sdk/index.js; the declaration entry is packages/sdk/dist/packages/sdk/index.d.ts. No published npm installation is assumed.
Use this wallet-bearing SDK in a trusted Node process. The website explorer uses public contract reads and does not require a private key or a gateway Bearer token in browser code.
BaseAgentConfig
| Field | Requirement and meaning |
|---|---|
| privateKey: string | Required local wallet key; load from private runtime configuration. |
| gatewayUrl: string | Required gateway origin. Resource calls must stay on that origin; redirects are rejected. |
| usdcAddress: string | Required compatibility field for the payment-token address, including when tokenAddress is supplied. |
| tokenAddress?: string | Preferred runtime token alias; takes precedence over usdcAddress. |
| rpcUrl?: string | Set explicitly. Fallback order is RPC_URL, ROBINHOOD_RPC_URL, then http://127.0.0.1:8545. |
| chainId?: number | Expected chain ID checked by setup. Pin it, and separately verify the local/mainnet RPC boundary. |
| gatewayApiToken?: string | Bearer credential for protected gateway routes; distinct from the facilitator token. |
| registryAddress?: string | Required for lifecycle operations and authenticated resource/result calls. |
| ledgerAddress?: string | Optional pinned Ledger. Lifecycle otherwise discovers it from Registry and validates both directions and the token. |
| pricePerCall?: bigint | Exact gateway price in base units; required together with registryAddress for authenticated call(). It is not automatically fetched from /status. |
Methods and transaction behavior
| Method | Behavior |
|---|---|
| setup() | Checks the network and reads native/token balances and token metadata. Creates lifecycle context when configured; sends no transactions. |
| getStatus() | With Registry configured, validates contract links and reads registration, score, deposit, debt/due time, limit, balances, and three allowances directly over RPC. Without it, returns balances and chain ID only. |
| register() | Reads DEPOSIT, approves that amount when allowance is insufficient, then registers. Already registered returns didSendTx=false. |
| approve(spender, amount) | Sends a token approval for registry, ledger, or permit2. Accepts a nonnegative bigint below MaxUint256; rejects an unlimited MaxUint256 approval. |
| revoke(spender) | Sends approve(spender, 0n). The same three spender names are supported. |
| call(resource, options?) | GET invocation with optional bytes32 requestId and auto/prepaid/credit mode. May authorize payment or trigger operator debt transactions. |
| getResult(requestId) | Signs a result-purpose GET for an existing request; does not initiate another charge. |
| settle() | Approves the exact observed debt if necessary and repays it in full. Returns didSendTx=false when debt is zero. |
| withdrawDeposit(to?) | Withdraws the deposit to the agent by default, only with zero debt. An already unregistered agent returns didSendTx=false. |
Return values
Authenticated successful calls expose success, requestId, data, charged, mode, payer, transaction, and resultHash, with optional paymentId and creditRecorded. The gateway serializes charged amounts as decimal base-unit strings. The SDK verifies the response identity and the hash of JSON.stringify(data).
setup and lifecycle status return bigint balances and scores. Despite their retained names, usdcBalance and usdcAddress refer to the configured payment token. getStatus does not currently populate the optional canCall or pricePerCall fields and does not establish service readiness.
Registration and repayment results can include approveTx as well as the business tx. A lifecycle result with didSendTx=false has no new business transaction. Legacy parameter-free /alpha calls without Registry configuration return the legacy response inside data, not the authenticated resource envelope.
Close a local test agent
Run this continuation only after all requests and prepaid score updates are reconciled, using the local agent from Quickstart. Repayment and withdrawal send transactions even when the contracts are paused. Revocation also sends a token transaction; invoke it only for nonzero allowances. These snippets are documentation and never execute in the website.
await agent.settle();
await agent.withdrawDeposit();
const status = await agent.getStatus();
for (const spender of ["registry", "ledger", "permit2"]) {
if ((status.allowances?.[spender] ?? 0n) > 0n) {
await agent.revoke(spender);
}
}
console.log(await agent.getStatus());Handle failures without duplicate writes
- For call/getResult failures, retain error.requestId. GatewayError exposes statusCode and body; a server AUTH_INVALID or CREDIT_EXHAUSTED code can be in body rather than a dedicated SDK error class.
- A second HTTP 402 after the single payment retry becomes PaymentRejectedError. Network failures and other non-200 statuses do not trigger another automatic payment attempt.
- Lifecycle transactions verify successful receipts and expected events. An uncertain send or failed receipt verification raises TransferFailedError and blocks subsequent writes through that lifecycle signer queue. Reconcile the original hash and nonce before further writes.
- The lifecycle queue covers instances sharing the same Signer object. It does not coordinate separate BaseAgent instances, other processes, or external users of the same wallet, and it does not impose a mainnet spending budget.