API guides

Agents on Rivet

How Gio and other agents discover, call and pay for your resources — and exactly which parts of that ship today.

What ships today is the v1 API and the Rivet MCP server; the examples and the tool list come from the contract this deployment serves. Provider tools, x402 resources and agent identity are not switched on yet, and each is tagged Coming below.

Rivet already lets an organization read and write its own side of the shared record over the v1 API. Agents add three things on top: a way to discover what a provider offers, a way to pay for a single request without an account, and an identity so the provider knows which business and which agent is calling. Each will get its own guide; this page is the map.

What ships today

A key acts as your organization. It reads documents, payments and treasury, writes documents where your environment has it enabled, and receives signed webhooks for the document lifecycle. An agent you run yourself can use all of this now: to the API it is a client holding a key, like any other.

List documents
From the live spec
curl "https://api.rivet.network/v1/documents?type=invoice" \
  -H "Authorization: Bearer rk_live_…"

Every response carries Rivet-Api-Version, and authenticated calls carry the rate-limit headers. Start with Getting started if you have never minted a key. An agent can also pay a Rivet invoice in USDC: Pay by agent documents the x402 version 2 challenge, and says whether it is live here.

The Rivet MCP server Available

For your own agent, calling Rivet. @rivet-network/mcp runs beside your agent and turns the contract this deployment serves into MCP tools: one per operation, named by its operationId, acting as your organization with the scopes of the key you give it. Add it to your MCP client:

MCP client config
From the published contract
{
  "mcpServers": {
    "rivet": {
      "command": "npx",
      "args": ["-y", "@rivet-network/mcp"],
      "env": {
        "RIVET_API_KEY": "rk_live_…",
        "RIVET_API_BASE": "https://api.rivet.network"
      }
    }
  }
}

The key goes in the environment, never in arguments or a committed file. A live organization’s keys start with rk_live_, a sandbox organization’s with rk_test_.

tools/list — 127 tools
From the live spec
getEnablement                 Which families this deployment can serve
getRates                      The rate card in force
getRatesVersion               One version of the rate card
listApiKeys                   List the organization's API keys
createApiKey                  Create an API key
revokeApiKey                  Revoke an API key
rotateApiKey                  Rotate an API key with a 24-hour grace
listDocuments                 List documents
createDocument                Create a document (draft)
getDocument                   Get a document
updateDocument                Edit a draft
listDocumentAttachments       List a document's attachments
getDocumentHistory            A document's verified history
getDocumentLineage            A document's lineage
exportDocumentProvenance      Export the verifiable proof bundle
getDocumentAttestation        The signed attestation (Rivet Finance)
issueDocument                 Issue a draft
transitionDocument            Transition a document
payDocument                   Pay a document
getPayChallenge               Read an invoice's x402 payment challenge
payWithX402                   Settle an invoice with a signed x402 authorization
financeOptIn                  Opt the organization in or out of the marketplace
listFinanceEligible           Your invoices, with their listing eligibility
browseFinanceListings         Browse open listings (pseudonymous)
createFinanceListing          List an eligible invoice
withdrawFinanceListing        Withdraw a listing
listFinanceListingInterests   The interests on your listing (funders pseudonymous)
expressFinanceInterest        Express interest in a listing
withdrawFinanceInterest       Withdraw your interest
consentFinanceInterest        Consent to disclosure (the lister's act)
getFinanceDisclosure          The disclosed introduction (the funder's read)
getFinanceSetup               Your finance setup
setFinanceRails               Name your accounts on a rail
listFinanceOffers             Offers, both directions
createFinanceOffer            Offer on a listing
getFinanceOffer               One offer
withdrawFinanceOffer          Withdraw your pending offer
acceptFinanceOffer            Accept an offer (creates the agreement)
listFinanceAgreements         Your agreements, both sides
getFinanceAgreement           One agreement
withdrawFinanceAgreement      Withdraw before funding (either party)
getFinanceRepayment           Repayment status
getSandbox                    Your sandbox's state
provisionSandbox              Create your sandbox
deleteSandbox                 Tear your sandbox down
resetSandbox                  Reset your sandbox
setSandboxMoney               Turn simulated Rivet Money on or off in your sandbox
advanceSandboxCounterparty    The counterparty acts
listWebhookEndpoints          List webhook endpoints
createWebhookEndpoint         Register a webhook endpoint
getWebhookEndpoint            Get a webhook endpoint
updateWebhookEndpoint         Update a webhook endpoint
deleteWebhookEndpoint         Delete a webhook endpoint
rotateWebhookSecret           Rotate the signing secret
pingWebhookEndpoint           Send a test event
listWebhookDeliveries         Recent deliveries
redeliverWebhook              Redeliver
getPaymentsContext            Payable and receivable rollups
listPaymentMethods            List payment methods
listTreasuryAccounts          List treasury accounts
listTreasuryBalances          List treasury balances
createShareItem               Add an HTML page or a link to the share drive
getShareItem                  Get a share item
listApps                      List the organization's apps
createApp                     Register an app
getApp                        Read an app
updateApp                     Change an app
listAppCredentials            List an app's secrets
createAppCredential           Mint a secret for an app
revokeAppCredential           Revoke an app's secret
requestAppReview              Ask Rivet to review an app
listAppInstalls               List who has installed an app
listInstalls                  List the apps the organization has granted access to
revokeInstall                 Revoke an app's access to the organization
getProgramAccess              What your organization can do with programs
listPrograms                  Your programs
createProgram                 Start a program
getProgram                    One program
updateProgram                 Change a program
listProgramEnrollments        The businesses in a program
inviteToProgram               Invite a business
getProgramPortfolio           Your programs and the businesses in them
listMyEnrollments             The programs your business is invited to or enrolled in
getMyEnrollment               One of your business's enrollments
updateMyEnrollment            Change what your lender reads, pause or end
acceptEnrollment              Accept a lender's invitation
submitReceivable              Share an invoice with your lender
withdrawReceivable            Take a submission back
listSharedReceivables         What your lender reads of each receivable
readEnrollmentBooks           Read your books now
listEnrollmentBuyers          Your customers with open invoices, and the buyers you share
updateEnrollmentBuyer         Include a buyer, leave it out, pause it, or set its contact
listEnrollmentReceivables     A business's receivables
getReceivableEvidence         One receivable's evidence
recordReceivableDecision      Decide a receivable yourself
getReceivableAttestation      A receivable's attestation
getReceivableBundle           A receivable's proof bundle, with its terms opened
exportEnrollmentReceivables   A business's receivables as a file
getUsage                      This cycle's usage, by the rate card's lines
listUsageEvents               List usage events
listUsageStatements           List the closed cycles' statements
getUsageLimit                 The usage limit
setUsageLimit                 Set the usage limit
getGoLiveStatus               Whether the organization may go live, and what is missing
acceptCoreTerms               Accept the core terms for the organization
getDocumentProofTerms         Open fields of an invoice's committed terms
listSigningKeys               List the organization's own signing keys
requestSigningKey             Ask for a key to sign for the organization
getSigningKey                 Get one signing key
revokeSigningKey              Revoke a signing key
proveSigningKey               Show that the key is held
createProofChallenge          Ask what to sign for a move of a document
signDocumentTransition        Move a document with your organization's signature
listConnections               List connections
inviteCounterparty            Invite a counterparty
acceptConnection              Accept a connection
getConnection                 Get a connection
verifyAttestation             Check an attestation by its digest
listAttestationKeys           The attestation public keys, as PEM
getAttestationKey             The key that signs attestations today
getLatestProofEpoch           The newest anchored epoch
getProofEpoch                 One anchored epoch
getProofAnchor                Where this deployment anchors
getProofHead                  A record's head in an anchored epoch, with its proof
getProofRegistryEntry         A pledge registry entry in an anchored epoch, with its proof
getAttestationJwks            The attestation public keys, as a JWK set
getSessionJwks                The session signing keys, as a JWK set

The agent docs are served beside the contract: Rivet for agents (the model, the first calls, recipes, every error) and MCP tools (every tool, with its effect, scope and inputs).

Provider tools on Connect Coming

A provider’s own resources will appear the same way, as tools with permissions attached, so an agent sees one tool list across the network and never a screen. How they are discovered will be published before providers need it.

x402 resources Coming

A priced resource answers 402 Payment Required with the standard x402 terms in the PAYMENT-REQUIRED header. Rivet’s client checks the calling agent’s authority — authorized, relevant to a transaction, within policy, vendor permitted — pays from the business’s wallet, and retries with the signed payment in PAYMENT-SIGNATURE. Your server verifies and settles through a facilitator, returns the resource, and both sides get a ledger line. The payment itself is the same x402 exchange. Anything else Rivet asks of your server, such as reading who is calling, will be published before you need it.

Price in dollars; settlement is USDC. The provider console converts at the time of the request and shows both on every line.

Agent identity Coming

Every organization already acts through its own Rivet network address. An agent gets one of its own — gio.meridian@rivet.network — under the business it acts for. Requests will carry both, so a provider can price, limit or refuse by agent, and every consequential action still names the person who approved it.

Where to go next