Skip to main content
A binds a third-party AI agent (Claude, OpenAI, Virtuals, Teneo, or your own) to an activated peaqOS machine (identity-verified, status active, and and homed on peaq or Solana according to the MCR API; otherwise 403 MACHINE_NOT_ACTIVATED) and attaches a that bounds what the agent can do on the machine’s behalf. Pairing is challenge-based: peaqOS issues a machine-bound , the agent signs it with the wallet key behind agentAddress ( personal_sign for an EVM key, over the raw UTF-8 bytes for a Solana key; the server picks the scheme from the address), and the orchestrator verifies the signature before persisting the pairing and issuing a signed session token. See the Machine Markets overview for base path, auth model, and common envelopes.

AgentPairing type

AgentPairingChallenge and AgentPairingProof

Signing a challenge

The server builds message and seals the agent, the scheme and the expiry into challengeId. The agent signs the returned message exactly as it is, line breaks included, and the proof { challengeId, signature } goes to the create-pairing or the session endpoint. The scheme follows from agentAddress, never from a client flag: An ed25519 pairing challenge message has twelve lines; the eip191 message keeps its existing form.
A worked example from the shared test vectors (orchestrator apps/api/test/fixtures/ed25519/challenge-vectors.json, entry agent-pairing.valid): this message, signed by the agent key 5BmfjRDHQTUmXajEQAkga5ks6b7za3DeBfGmxfFkv1nv, gives the signature QcLBtQvsD219CHy3PUUbcxUe3Z6P7tUpYE4fMqBEb8K6kb9SHB5ThxhsHZdtrpLVs7Sb7p12VLtWWGfCeDqw1LD. Verifying it over the message’s UTF-8 bytes under that key succeeds; change any line and it fails.
A pairing created with an ed25519 proof, as the endpoint returns it (agentDid was omitted on the request, so the server derived the mainnet form; ids, keys and timestamps are a run’s own):
A challenge is stateless: the scheme, the signer and the expiry are HMAC-sealed into challengeId, no nonce is consumed, and a { challengeId, signature } pair is accepted again until expiresAt (10 minutes by default, PEAQOS_IDENTITY_CHALLENGE_TTL_MS and PEAQOS_AGENT_PAIRING_CHALLENGE_TTL_MS; a session token lasts 1 hour, PEAQOS_AGENT_PAIRING_SESSION_TTL_MS). For an ed25519 challenge the orchestrator answers these codes on the create-pairing and session endpoints; an eip191 proof keeps the AGENT_PAIRING_PROOF_* codes. The full contract (common rules, both message layouts, the shared vectors) is the SVM-SIGN Wire Contract.

Endpoints

GET /machines/:machineId/agent-pairings

POST /machines/:machineId/agent-pairings/challenges

Returns a fresh challenge for an agent. The Machine Agent signs item.message with the wallet key behind agentAddress, in the scheme verificationMethod names (see Signing a challenge), then submits the signature to the create-pairing endpoint or the session-rotation endpoint.
The agent’s DID takes one of two forms. For an EVM agentAddress it is did:pkh:eip155:<chainId>:<address>: omitted, the orchestrator derives did:pkh:eip155:1:<checksummed address>; supplied, it may carry any chain id but must name the checksummed agentAddress. For a Solana agentAddress it is did:pkh:solana:<reference>:<base58 key>, where <reference> is the first 32 characters of the cluster’s genesis hash (mainnet 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, devnet EtWTRABZaYq6iMfeYKouRu166VU2xqa1): the orchestrator has no Solana cluster configuration, so an omitted agentDid is derived with the mainnet reference, and a devnet agent supplies its DID; a supplied Solana DID must name the mainnet or the devnet reference and the exact key. Anything else returns VALIDATION_ERROR. Pass the same agentDid to the challenge request and the create-pairing request.

POST /machines/:machineId/agent-pairings

Creates a pairing. Requires agentProof when pairing verification is enabled (production default); the proof is { challengeId, signature } in both schemes. Returns the pairing with a signed session JWT in pairingToken. The token is returned once at create; rotate via the sessions endpoint.
Errors: AGENT_PAIRING_PROOF_REQUIRED, AGENT_PAIRING_PROOF_INVALID, AGENT_PAIRING_PROOF_EXPIRED (eip191 proofs); PROOF_METHOD_MISMATCH, PROOF_SIGNATURE_INVALID, PROOF_SIGNER_MISMATCH, PROOF_EXPIRED (ed25519 proofs, see Signing a challenge); AGENT_PAIRING_UNAVAILABLE, MACHINE_NOT_ACTIVE, MACHINE_IDENTITY_PROOF_REQUIRED, VALIDATION_ERROR.

POST /machines/:machineId/agent-pairings/:pairingId/sessions

Rotates the session JWT for an active pairing. The agent gets a fresh challenge, signs it, and submits the new proof here. The fresh challenge is requested with the pairing’s stored agentAddress, agentProvider, agentRole and, when the pairing was created with a supplied agentDid, that same agentDid; the orchestrator verifies the proof against the stored pairing, not the request, so omit agentDid only when it was server-derived. Returns the pairing with a new pairingToken. The ed25519 codes of Signing a challenge apply here too.
Default session TTL is 1 hour (PEAQOS_AGENT_PAIRING_SESSION_TTL_MS). Market writes reject expired tokens with AGENT_AUTH_EXPIRED and reject tokens whose delegationPolicyHash no longer matches the persisted policy.

PATCH /machines/:machineId/agent-pairings/:pairingId

Repolicy or pause/resume. Policy changes invalidate the current session token’s delegationPolicyHash. Rotate the session via POST .../sessions after a policy change.

DELETE /machines/:machineId/agent-pairings/:pairingId

Revokes the pairing. The current session token is invalidated. Subsequent market-search calls with that token return AGENT_AUTH_INVALID or AGENT_PAIRING_INACTIVE. If no active pairing exists for a machine, market writes return AGENT_PAIRING_REQUIRED (409). If the pairing has open market orders (status not in confirmed, cancelled, or failed), the call returns OPEN_MARKET_ORDERS (409) with orderIds. Cancel or settle those orders first, then retry.

Session JWT claims

The pairingToken is an HS256 JWT signed by the orchestrator. Claims:
The orchestrator re-verifies the signature, expiry, pairing status, and delegationPolicyHash against the persisted policy on every market write.

Delegation policy

Enforcement is server-side. Spend-limit violations return AGENT_SPEND_LIMIT_EXCEEDED or AGENT_DAILY_LIMIT_EXCEEDED. Allow/denylist violations return AGENT_POLICY_DENIED.