Agents / API 1.27
Agent Trading API | Wallet Signing, Sessions & Recovery
Execute supported swaps, bridge steps, perpetual orders, Earn actions and treasury transactions. Set customer permissions, review fees and recover a submission.
Use your own wallet
Use the SDK with new BitpontClient(). It creates a private workspace automatically. Save client.workspace on the server and pass it back as {workspace} after a restart. REST and remote MCP clients can call openWorkspace and reuse the secret in X-Bitpont-Workspace or the workspace tool input. The wallet signs every trade or explicitly approves an exact customer session.
import {BitpontClient} from './bitpont-client.mjs';
import {prepareAction, executeTicket} from './execution.mjs';
const client = new BitpontClient({workspace: process.env.BITPONT_WORKSPACE});
// input and requestId come from a persisted, validated intent.
const ticket = await prepareAction(client, 'assetPrepare', input, requestId);
// createAgentWalletSigner in execution.mjs supports EVM, Solana and typed orders.
const result = await executeTicket(client, ticket, yourWalletSigner);
console.log(result.executionId, result.state, result.networkId);Use your referral programme
Use the referrals MCP product profile or call referralIntent with dashboard, history, accept or request-payout. Sign the returned exact message with your Solana wallet and call referralApply with the same inputs, timestamp and signature. Receipt history supports a source filter and the nextCursor value as after. A payout request enters treasury review.
Verify a received fee
Unpaid use shares the standard request budget. A finalized, verified Bitpont fee unlocks an hour without the standard request quotas, measured from its on-chain payment time. Call feeAccess on your submitted ticket, sign the returned workspace challenge locally, then send ownerSignature. The same verified payment cannot extend the window on replay. Further qualifying fees renew it. Jupiter, supported Kyber inputs and deBridge affiliate receipts have verifiers. Unsupported receipts, quotes, gas and pending settlements use the standard budget. Provider capacity and concurrency still apply.
Check a sequence before requesting signatures
Use GET /api/v1/agent/execution/routes for the current action names and schemas. Send up to twelve ordered {action,input} steps to POST /api/v1/agent/execution/plan or call bitpont_executionPlan. Each step reports the exact field path to fix. Planning costs one request unit and creates no tickets.
After validating the inputs, prepare each action with a unique request ID and the same private workspace. Review the fresh fee, amount, network and wallet at preparation. Wait for the required settlement before preparing any dependent step. There is no atomic guarantee across steps. For Derive orders, use the wallet-local Options kit.
Connect your integration
Read the execution catalogue for action names and input schemas. The REST operation IDs are also MCP tools with the bitpont_ prefix. Use a private workspace to prepare, submit and track wallet-signed trades. Named partner keys retain their configured scopes. Email [email protected] for high-volume access.
Sign with a funded agent wallet
- Choose an action and call executionPrepare with its input and a persistent requestId UUID. Save the executionId and deadline. Continue to signing only for an unexpired awaiting-signature ticket that includes a signing payload. For no-action, inspect the returned review before continuing. If initialization is required, review the account setup separately and prepare the action again after setup.
- Compare the network, wallet, token addresses, amount, minimum output, fee and destination against your intent. For EVM, populate the nonce and bounded gas fields from the correct chain, then sign the returned transaction locally. For Solana, deserialize the versioned transaction, preserve co-signatures, sign the unchanged message and encode the wire transaction as base64. For venue orders, sign the displayed typed data on the specified domain.
- Submit signed bytes or the signature through executionSubmit. Save the network hash, client order ID, CoW UID or venue reference before continuing. Use executionStatus and the product receipt to verify the outcome.
Approve and revoke a customer session
Call sessionPrepare with one customer wallet and up to 12 exact unsubmitted ticket IDs. Show the wallet, integration, each action and expiry. The customer wallet signs the listed transaction payloads and the session message. Wallets with batch signing can group this review. Other wallets can prompt for each underlying signature during setup. A session lasts until the earliest ticket deadline, at most 90 seconds. Use sessionActivate inside the trusted customer application. The agent then calls sessionRun with the two IDs. sessionStatus shows the permitted actions and their state. sessionRevoke stops the remaining submissions. The customer can also use ownerRevokeSession without the partner key by signing the revocationMessage returned at setup. Keep the sessionId and this message in the owner’s wallet application. It cannot reverse a transaction already sent. Never expose pre-signed payloads to the model.
Stop a customer session
Enter the session ID from the application that requested approval. Sign with the same wallet to stop any unused tickets.
Run recurring EVM actions
The downloadable kit includes recurring-evm.mjs for a customer-controlled unattended signer. Use Node 24, ethers 6 and an owner-only persistent SQLite file. Open the module with a trusted Bitpont client, signer and RPC provider. The owner grants one reviewed EVM call with exact calldata, value, recipient, wallet and chain. The grant also fixes inputs, run count, deadline and gas ceilings. A fresh ticket must match on every run. Changed prices, calldata or targets may require new consent. Each attempt consumes one slot, even when it fails. Give the agent access to run and status in a separate process. Restrict grant, revoke, cancelUnsent, the database and signing credentials to the owner. A regular browser wallet may still prompt if used as the signer.
Each run takes a persisted request UUID. The helper records the signed transaction hash before submission. For a lost response, use recover with the same UUID. An uncertain broadcast blocks new sends from that database. cancelUnsent can release an interrupted preparation before transmission. Keep the database on durable storage and use one writer service per wallet.
Delegate a Hyperliquid trading key
For a supported main account, generate a fresh trading key in the owner-controlled integration, then prepare hyperSession and sign the venue approval as the owner. Choose 1–60 minutes. Supply that signer address to hyperOrder and hyperCancel. Supported perpetual accounts can also use hyperLeverage and hyperMargin after a fresh market and position check. Bitpont rechecks the venue permission before submission. The native key grants venue trading authority. Changing an agent-side setting cannot narrow that key on the venue. End the Bitpont-named permission with owner-signed hyperRevoke. Read venue permissions to confirm replacement. Configure builder fees explicitly and prepare hyperBuilder for the owner’s fee approval when required.
Authorize a Treasury executor
Where the verified Bitpont Safe module is deployed, use safeRuleStage to prepare enable, authorize, revoke or disable. Each Safe owner approves the same proposal hash. Execute the threshold-approved proposal with its expectedHash. A rule fixes its executor, permitted calls, before and after checks, interval, expiry, gas price and run count. The agent signs safeRuleRun with its own gas-paying wallet and the expected on-chain run index. The module enforces the rule at execution. Confirm the Executed event and balances. Discover configured deployments with the operations tool. Installing this release does not deploy a contract or enable a module on any Safe.
Follow the product settlement
- Swaps and bridges use the reviewed allowance, spend, minimum output and fee policy. Prepare each required approval and funding step separately and confirm the destination delivery.
- Earn and liquidity calls preserve protocol minimums, additional signers, vault checks, position identities and the order of dependent steps.
- Solana perpetuals require a detached wallet proof on the exact native preparation request, followed by a signed transaction. GMX and Ostium use their respective builders. Hyperliquid orders use venue signatures. A resting or partially filled order can still have remaining size.
- Safe proposals require the configured owner threshold. Inspect safeReceipt after execution. The Operations composition planner describes dependencies. Prepare each supported step only after its input is available.
Recover a timeout or interruption
Read executionStatus before repeating a write. An unknown response can follow a successful broadcast. Keep the raw transaction hash or venue ID before sending. The server journals request IDs, signature digests and recovery references in its private account database for seven days. It writes the broadcast state before contacting the provider. After a restart, executionStatus can recover a receipt. Unsigned preparations and unspent batch signatures expire with the serving process. Use sticky routing for active sessions. A client can recover the result on the chain or venue even after database retention ends. On-chain inclusion, a fill and destination delivery are separate events. Each fee-bearing adapter reports its own fee terms. Some protocols have no Bitpont fee.
Trade Derive options from an agent wallet
Download the agent starter kit and run node bitpont-options-mcp.mjs with Node 24 or newer on the wallet owner’s machine. Set BITPONT_OPTIONS_SIGNER to a local signer module, BITPONT_OPTIONS_POLICY to the owner policy JSON and BITPONT_OPTIONS_STATE_DIR to one durable private directory for this wallet. The kit includes working signer and policy examples. An eligible funded Derive subaccount is required.
Use bitpont_optionsAccount to check positions and margin. Call bitpont_optionsPrepare with a new request ID, exact instrument, side, quantity, limit price and fee limit per unit. bitpont_optionsEstimate requests the venue estimate. bitpont_optionsPlace refreshes it and submits the same locally signed order once. bitpont_optionsStatus reconciles open orders and history. bitpont_optionsCancel targets its open remainder. Use the same request ID after a timeout.
The order uses the same client attribution and fee fields as the Bitpont Options workspace. A separate Bitpont options fee is not added.
The owner policy sets the subaccount, quote currency, named instruments, expiry, maximum order count, size, premium plus fee per order, and fee per unit. A prepared order consumes one slot for the lifetime of the journal. Keep one journal per wallet and back it up with the signer configuration. Premium limits describe the order amount. An opening short can lose more than its premium. Opening shorts require an explicit policy change. The local Options signer is independent of hosted customer sessions.
Track new tools and permissions
Connect directly to the hosted MCP for current tools. With the downloadable stdio server, run node bitpont-agent-mcp.mjs --live to load the current published contracts at startup. Add --product earn to load the Earn profile. Restart when the contract revision changes.
Read GET /api/v1/integrations/manifest using the same credentials as your agent. Store the ETag and send it in If-None-Match on subsequent reads. A 304 response means the tool schema and effective access are unchanged. A changed schemaRevision signals that the published tool contract changed. Fetch the current tool catalogue and refresh the affected schemas. The manifest lists configured routes and authorization separately. Higher API limits are available from [email protected].
Inspect balances before a Solana Earn action
Use solana-earn.providers and solana-earn.products to find configured providers and exact products. Read solana-earn.portfolio for balances and incomplete providers. For Jupiter borrowing use jupiter-lending.vaults, jupiter-lending.vault, jupiter-lending.portfolio and jupiter-lending.position. Continue position scans with both nextCursor and scanId. For Marinade use marinade.state for pool parameters and marinade.account for balances and delayed withdrawal tickets.
Recover an execution by request ID
If the preparation response is lost, use bitpont_executionLookup with the original request UUID. To resume after a restart use bitpont_executionReceipts with your private workspace or submit-scoped partner key. It lists saved receipts newest first. Pass nextCursor as before to continue. The seven-day journal contains the current integration’s tickets. Use bitpont_executionStatus on the matching execution ID for live settlement checks. Local Options orders use their separate local journal.
Trace a bridge fee from source order to recipient
Use bridgeFeePolicy for Bitpont’s source recipients. Direct cross-chain DLN quotes use referral 33127 and a 0.40% input fee. A 1,000 USDC input implies 4 USDC before any source asset conversion. Preserve the order ID, source network, source transaction and expected input units. Call bridgeFeeFollow with the source network and order ID to resolve the next step. It checks the source chain and matches receipt evidence where available. For an older Solana claim, supply its withdrawalSignature. The kit includes bridge-fee-status.mjs for this read. Ask bridgeFeeOrders for unlocked candidates. An empty page or a destination delivery says nothing about a recipient credit.
On EVM, call bridgeFeeReceipt with the creation and source unlock hashes. If the fee is deferred, check bridgeFeeBalance, use bridgeFeeWithdraw with an externally signing gas payer and check bridgeFeeWithdrawalReceipt. The payout address is fixed. Deferred withdrawals aggregate fees by token. Native transfers need trace-capable RPC to prove receipt.
On Solana, read solBridgeFeeState for the exact order. Once claimable, the configured Solana beneficiary can authorize solBridgeFeeWithdraw. Use either withdrawal action with executionPrepare, sign in the appropriate wallet, executionSubmit, then executionStatus. Call solBridgeFeeReceipt with the order ID and finalized signature to verify the recipient’s token credit. Same-chain Jupiter referral claims use their own referral key and dashboard. The Solana cross-chain beneficiary is a separate identity.
Check recurring swap permissions on a Safe
Use recurringPermissions with the chain, Safe address and owner to check whether the installed module and account qualify. The supported rule targets a configured Base Safe exchanging USDC and WETH through one fixed pool. The authorization binds the input amount, minimum output, Safe recipient, executor, interval, expiry and execution budget. Read the quoted input-token fee in the rule before owner review.
Generate the exact rule with recurringSwapRule. Review proposal in Base Treasury automation, then retain ruleId for execution or revocation. Validity and interval values use seconds. Gas price bounds use wei per gas. Only an enabled, verified deployment can authorize execution. Existing signed ticket sessions remain available for individual trades. Borrowing and Multiply require their respective wallet-signed actions. Review customer session and revocation options.
Simulate an existing EVM ticket
Read walletTokenBalances for native gas and the exact ERC-20 input balance. Use walletAllowances for the token and spender returned in the quote. In the original private workspace, POST the saved executionId to /api/v1/agent/execution/preflight. Read the call result and gas estimate independently. After signature and submission, follow executionStatus and the supported swap receipt for settlement evidence.